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About This Manual 



Purpose 

The A Series DMSII Interpretive Interface Programming Reference Manual describes 
how to code effective and efficient application programs that access and manipulate a 
Data Management System n (DMSII) database, usii^ the DMSII interpretive interface. 



Scope 



This manual details how to code DMINTEBPRETEB library entiy points and how to 
generate the DMINTERPRETER library 

Audience 

This manual has two primary audiences: application programmers who are responsible 
for programs that report or update information in a DMSII database and database 
administrators who generate the DMINTERPRETER librazy. 

Prerequisites 

Before programming DMSII applications, you should be familiar witii 

• Basic A Series concepts 

• Basic DMSn concepts 

• The Data and Structure Definition Language CDASDL) 

• libraries and entry points 

• The prograniTning languages you intend to use 

You should also know how to use the A Series Command and Edit (CANDE) message 
control system (MCS) to enter code and know how to use CANDE and the Work Flow 
Language (WFL) to compile and run jobs. 
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How to Use This Manual 

This manual is designed as a reference to help you code effective and efficient DMSn 
application programs that use the interpretive interface. 

If you are new to the interpretive interface, read Section 1 for an overview of the 
interface. Next, read Section 2 for an explanation of how to access the library and entry 
points in your application program. Then read Sections 3 through 6 for information on 
coding entry points. 

If you are an esiperienced DMSII interpretive interface programmer, you can go directly 
to the entry point explanations in Sections 3 throu^ 6. The entry points are divided by 
task: 

• Section 3 covers tasks performed by standard entry points. 

• Section 4 deals with data transfer tasks. 

• Section 5 focuses on exception-handling tasks. 

• Section 6 explains attribute setting. 

Use either the table of contents or the index to locate a specific task or entry point. 

If you are writing a general-purpose program that can access any database and is 
data independent, read Section 7 for information on how to use DBSTRUCTURE, an 
intrin^c, read-only data set. 

While Section 5 presents coding guidelines for handling exceptions and error conditions 
within your appKcation program, Appendix B details the actxial exception and error 
messages returned by the Accessroutines to your application program. 

Database administrators and programmers who are responsible for the 
DMENTBKPKETEK library should read Appendix A carefully before generating the 
library. 

Althou^ the interpretive interface can be used by any programming language that can 
import library objects, only ALGOL, COBOL74, and FORTRAN?? program fragments 
are used for text examples. The samples of complete programs, in Appendix C, are 
also given only for ALGOL, COBOL74, and FORTRAN??. If you are programming in 
another language, sudi as C, COBOL, COBOL85, Pascal, or PL/1, consult the language 
reference manual. 

The separate COBOL languages (COBOL, C0B0L?4, and COBOL85) are referred 
to collectively in the text, index, and glossary as COBOL. However, if there are any 
differences, the specific ANSI-version of the langus^e is identified. 

To distir^uish interpretive interface entry points from language extensions, the text 
notes the entry points by their COBOL name in the DATABASE/DMINTERPRETER 
file. For example, while both DBFTND and FIND refer to the find operation, DBFIND is 
the entry point and FIND is the command. 
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The entry points for transferring data from the user work area to iiser-declared 
variables are referred to collectively as DBGET entry points. The entry points for 
transferrii^ data from user-declared variables to the user work area are referred to 
collectively as DBPUT entry points. 

Metatokens are used for describing syntactical elements. For example, the metatoken 
< data set qualified name > refers to the syntax of a data set name. Syntax diagrams 
and syntax elements are noted in the index imder the appropriate metatoken. An 
explanation of railroad diagrams (a Unisys method of depicting syntax) is found in 
Appendix D. 

This manual uses the word access as both a noun and a verb. 

• As a noxm, Access always appears with a capital A and refers to a database part. 

• As a verb, access means to use or retrieve something. 

This manual also uses the word recreate as both a verb and a DMSn operation. 

• As a verb, re-create always appears with a hyphen, 

• As a DMSn operation, recreate always appears without the hyphen. 

Throughout the document, A Series is used to refer collectively to A Series and B 7900 
systems. Unless otherwise noted, aU references to related documentation within 
the text are for A Series product information. These references are included in the 
bibliography. AU acronyms used in the guide, including those used in docimientation 
titles, are spelled out and defined in the glossary. 

For a broader view of progranmiii]^ DMSn applications, you can also do the following: 

• Consult the A Series DMSII Technical Overview for background information and for 
an explanation of designing and maintaining databases. 

• Read the A Series DMSII Application Program Interfaces Programming Guide for 
general guidelines and for an introduction to both the interpretive interface and the 
language extensions interface. 

• Read the A Series DMSII Data and Stntcture Definition Language (DASDL) 
Programming Reference Manual for DASDL option specifics. 

• Refer to the A Series DMSII Utilities Operations Guide for detailed information on 
the use of DMSII programs. 

Organization 

This manual is organized into seven sections. Each section explores topics and tasks that 
pertain to the DMSII interpretive interface. In addition, four appendixes, a glossary, a 
bibliography, and an index appear at the end of the guide. 

Section 1. Understanding the DMSII Interpretive Interface 

Section 1 overviews the basic structure and advantages of the interpretive inter&ce. 
It introduces the major components of the interface and presents programming 
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considerations, recommendations, and guidelines that pertain to the interpretive 
interface only. 

This section also overviews the four types of entry points provided by the 
DMENTERPRETER library: the standard, data transfer, exception handling, and 
attribute setting entry points. 

Section 2. Accessing the Interpretive Interface 

Section 2 explains how, for each supported user language, an application program can 
access both a DMINTERPRETER library and its task-specific entry points, and then 
invoke the entry points. 

Section 3. Manipulating the Database 

Section 3 details the function and coding of each standard entry point to the 
DMINTERPRETER library. Tliese entry points perform functions comparable to those 
performed by language extensions in manipulating the database, such as opening the 
database, finding records, creating new records, changing records, and storing records. 

Section 4. Transferring Data 

Section 4 details how the user areas are made available and how each data transfer entzy 
point to the DMINTERPRETER library is coded. 

Sections. Handling Exceptions 

Section 5 details the fxmction and coding of each exception handling entry point to the 
DMINTERPRETER library 

Section 6. Restricting Calls to the Accessroutines 

Section 6 details the function and coding of the attribute setting entry point to the 
DMINTERPRETER library, the ^try point that restricts the nimiber of calls to the 
Accessroutines. 

Section?. Determining the Database Structure 

Section 7 discusses how to use the data set DBSTRUCTURE to determine the structure 
of the database at run time. 



Appendix A. Generating the DMINTERPRETER Libraiy 

Appendix A details how to generate the DMINTERPRETER library either through the 
Work Flow Language (WFL) or intCTactively through the program BUILDINQ. The 
library can interface with an entire physical database, a logical database, or selected 
parts of a database. 
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Appendix B. DMSn Exceptions and Errors 

Appendix B lists the exceptions and errors returned to an application program by the 
Accessroutines. 

Appendix C. Sample Programs That Use the Interpretive Interface 

Appendix C contains the reqiiired DASDL description and the listing for ALGOL, 
COBOL74, and FORTRAN?? application programs that demonstrate possible coding 
techniques for programs that use the interpretive interface. 

Appendix D. Understanding Railroad Diagrams 
Appendix D explains how to read railroad diagrams. 

Related Product Information 

The following list contains companion Unisys documents for this guide. 

A Series ALGOL Programming Reference Manual, Volume 1: Basic 
Implementation (form 8600 0098) 

This manual describes the basic features of the Extended ALGOL programming 
language. This manual is written for programmers who are familiar with programming 
concepts. 

A Series ALGOL Programming Reference Manual, Volume 2: Product 
Interfaces (form 8600 07S4) 

This manual describes the extensions to the Extended ALGOL language that allow 
application programs to use the Advanced Data Dictionary System (ADDS), the 
Communications Management System (COMS), the Data Management System IE 
(DMSn), the Screen Design Facility Plus (SDF Pl\is), or the Semantic Information 
Manager (SIM). This manual is written for programmers who are familiar with Extended 
ALCtOL programming language concepts and terms. 

A Series ALGOL Test and Debug System (TADS) Programming Guide 
(form 1169539) 

This guide describes the featm-es of ALGOL TADS, an interactive tool used for testing 
and debugging ALGOL programs and libraries. ALGOL TADS allows tiie prc^rammer 
to monitor and control the execution of programs under test and examine tilie data at any 
given point during program execution. This guide is written for programmers who are 
familiar with ALGOL programming language concepts and terms. 

A Series C Progrcanming Reference Manual (form 3950 8775) 

This manual describes the C programming language, uicluding the A Series extensions. 
Where the implementation of A Series C differs from the proposed draft ANSI C 
standard, the differences are noted in the manual 
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A Series COBOL ANSI-68 Programming Reference Manual (form 8600 0320) 

This manual provides a complete description of COBOL as developed by the CODASYL 
Conmotittee and described by the American National Standards Institute in Xd.23-1968. 
This manual is written for programmers who are familiar with progranmiing concepts. 

A Series COBOL ANSI'74 Programming Reference Maniicd, Volume 1: Basic 
Implementation (form 8600 0296) 

This manual describes the basic featxires of the standard COBOL ANSI-74 programming 
language, which is fully compatible with the American National Standard, X3.23-1974. 
This manual is written for programmers who are familiar with programming concepts. 

A Series COBOL ANSI'74 Programming Reference Manual, Volume 2: Product 
Interfaces (form 8600 0130) 

This manual describes the extensions to the standard COBOL ANSI-74 language. 
These extensions are designed to allow application programs to interface with the 
Advanced Data Dictionary System (ADDS), the Commimications Management S3rstem 
(COMS), the Data Management System n (DMSII), the DMSII Transaction Processing 
System (TPS), the Screen Design Facility (SDF), the Screen Design Facility Plus (SDF 
Plus), and Semantic Information Manager (SIM) products. This manual is written for 
programmers who are familiar with COBOL74 programming language concepts and 
terms. 

A Series COBOL ANSI'85 Programming Reference Mcmual, Volume 1: Basic 
Implementation (form 8600 1518) 

This manual describes the basic features of the COBOL ANSI-85 programming language, 
as implemented on Unisys A Series systems. This manual is written for programmers 
who are familiar with programming concepts. 

A Series COBOL ANSI-85 Programming Reference Manuctl, Volume 2: Product 
Interfaces (form 8600 1526) 

This manual describes the extensions to the standard COBOL85 language. These 
extensions are designed to allow application programs to interface with the 
Commtmications Management System (COMS) and Data Management System IE 
(DMSn) products. This manual is written for programmers who are familiar with 
COBOL85 programming language concepts and terms. 

A Series DMSII Application Program Interfaces Programming Guide 
(form 5044225). Foimerly A Series DMSU User langucigelnterfiuse 
Programming Guide 

This guide ej5)lains how to write effective and efficient application programs that access 
and manipulate a Data Managem^t System H (DMSII) database using either the 
DMSn int^retive inter&ce or the DMSII language extensions. This guide is written 
for application programmers and database administrators who are already familiar with 
the basic concepts of DMSII. 
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A Series DMSIIData and Structure Definition Language (DASDL) 
Programming Reference Manual (form 8600 0213) 

This manual provides instructions for defining and maintaimng a Data Management 
System 11 (DMSII) database usiag DASDL. This manual is written for database 
administrators and staff. 

A Series FORTRAN?? Programming Reference Manned (form 3950 8759) 

This manual describes the FORTRAN 77 programming language, which is fully 
compatible with the American National Standard X3.9-1978. This manual is written for 
programmers who are familiar with programming concepts. 

A iSeries FORTRAN?? Test and Debug System (TADS) Programming Guide 
(form 1222667) 

This guide describes an interactive tool for testing and debugging FORTRAN77 
programs and libraries. This manual is written for programmers who are familiar with 
FORTRAN77 programming language concepts and terms. 

A Series Task Attributes Programming Reference ManucU (form 8600 0502). 
Formerly A Series Work Flow Administration and Programming Guide 

This manual describes aU the task attributes available on A Series systems. It also gives 
examples of statements for reading and assigning task attributes in various programming 
languages. The A Series Task Management Programming Guide is a companion 

A Series Task Management Programming Guide (form 8600 0494). Formerly 
Work Flow Administration cmd Programming Guide 

This guide explains how to initiate, monitor, and control processes on an A Series system. 
It describes process structures and process family relationships, introduces the uses of 
many task attributes, and gives an overview of interprocess communication techniques. 
The A Series Task Attributes Programming Reference Manual is a companion manual. 
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Section 1 

Understanding the DMSII Interpretive 
interface 



There are two DMSII application program interfaces: 

• The DMSn language extensions 

• The DMSn interpretive interface 

The language extensions are e^lained in Volimie 2 of the ALGOL, COBOL, COBOL74, 
COBOL85, and BPG reference mannals. The interpretive interface is detailed in this 
manual. Consult the DMSII Application Programming Guide for a comparison of the 
language extensions and the interpretive interface. 

This section describes the major features of the interpretive interface. 

Compilers That Can Use the Interpretive Interface 

Only a standard language compiler that can import library objects can use the 
interpretive interface. For A Series sjrstems, this restriction means that application 
programs written for use with the following compilers are able to use the interpretive 
interface: • 

ALGOL C0B0L74 Pascal 

C COBOL85 PL/1 

COBOL FORTRAN?? RPG 

Interpretive Interface Run-Time and Compile-Time 
Interfaces 

The interpretive interface uses the standard language compiler as its compile-time 
interfSace and the Accessroutines as its run-time interface. The standard language 
compiler is responsible for producing the error-free object code jSle for your application 
program. The Accessroutines communicate with tiie database, allowing you to write and 
compile application prc^ams before the database is compiled. The s^lication program 
never directly accesses the database. This arrangem^t means that 

• A single application program, throu^ the library mechanism, can invoke as many 
databases as desired. (A DMINTEBPRBTEB library must be compiled for each 
database.) 

• You can use the open operation to create general-purpose programs that can access 
any database. - 
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• You can postpone decisions about database operations until run time. 

• Programs can use the intrinsic data set DBSTRUCTUKE to interrogate the 
structure of a database at run time. 

Figure 1-1 shows the modules and timing involved in compiling an application program 
that uses the interpretive interface. 
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Figure 1-1. Database Processing with the Interpretive Interface 
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Using the Run-Time Libraries 

The interpretive interface uses two run-time libraries: the DMSUPPORT library and 
the DMINTERPRETER library. 

• The DMSUPPORT library provides entry points that allow you to obtain DMSII 
error and exception codes. 

• The DMINTERPRETER library provides entry points that allow your program to 
access the database. 

Reporting Errors through the DMSUPPORT Library 

The DMSUPPORT library is a general support library used with all DMSII software. 
The library provides error messages and exception handling for aU DMSII software. 

For more information about exception handling through entry points, read Section 
5, "Handling Exceptions." For details about the exception and error messages, read 
Appendix B, "DMSII Exceptions and Errors" and the DMSII Application Programming 
Guide. For a details of the DMSUPPORT library, consult the DMSII Utilities 
Operations Guide. 

Accessing a Database through the DMINTERPRETER Library 

The DMINTERPRETER library provides entry points that allow application programs to 
access, manage, and manipulate a DMSII database without executing DMSII langug^ 
extensions. Section 2, "Accessing the Interpretive Interface," e:q)lains how to access the 
library and the entry points. 

Each entry point is a procedure in a library program (known as a library) that can be 
called by another program through a process known as exporting. A library e^orts 
entry points, and the calling program imports entry points. Exporting allows the library 
procedure to be accessed by programs that are external to the library. Sections 3 
through 6 detail the DMINTERPRETER library entry points. 

Each database has it own DMINTERPRETER library written in DMALGOL. Using 
the program BUILDINQ, the database administrator generates the library after 
compiling the DASDL description for the database. Read Appendix A, "Generating the 
DMINTERPRETER Library," for the details of executing BUILDINQ. 

Identifying the Four Types of DIVIINTERPRETER Entry Points 

The interpretive interface uses four types of entry points: standard, data transfer, 
exception handling, and attribute setting. Each type p^orms a spedfic ftmction, as 
shown in Table 1-1. 
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Table 1-1. Purpose of Each Type of Entry Point 



lype 






Standard 


Performs functions that correspond to functions 
specified in DMSli language extensions. For 
example, both interfaces provide a means of 
opening and closing a database. 


Section 3, 
"Manipulating 
the Database" 


Data transfer 


Moves data iDetween the database and the user, 
work area, and between the user work area and 
the program. 


Section 4, 

'Transferring 

Data" 


Exception 
handling 


Returns result of a call. The result reports whether 
the call was successful and, if it was not 
successful, the category, subcategory, and 
structure number associated with the exception. 


Section 5, 
"Handling 
Exceptions" 


Attribute setting 


Restricts the number of times the 
DMINTERPRETER library can call the 
Accessroutines to complete a find operation. 


Section 6, 
"Restricting Calls 
to the 

Accessroutines" 



Accessing DIVI INTERPRETER Library Entry Points 

DATABASE/DMINTERPKETER, the DMINTERPRETER library symbolic file, contains 
declarations of library entry points for each language. Depending on which user 
language you use to code your program, you must use different procedures and syntax to 
access (import) the esqported declarations. 



For ALGOL and FORTRAN?? Programs 

If you are coding either an ALGOL and FORTRAN?? program, you must follow a 
three-step process to access entry points: 

1. Dedare the library. 

2. Declare the entry points. 

3. Invoke the entry points. 

Once the DMINTERPRETER library for the database is established, declare the entry 
points either by 

• Using the $INCLUDE compiler control option to declare all the entry points 

• Declaring each entry point individually 

If you use the $INCLUDE option, all the entry points are exported. If you declare entry 
points individually, you can create your own subset of entry points and you can rename 
the entiy points. 
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Once an entry point is declared, it can be invoked (called) to perform its run-time 
function. 

Read Section 2, "Accessing the Interpretive Interface," for detailed explanations of how 
to access the library and how to use the $INCLUDE compiler control option. 



For COBOL Programs 

If you are coding programs in any supported COBOL language, you must follow a 
two-step process to access entry points: 

1. Declare the library. 

2. Invoke all the entry points. 

Once the library is established, the entry points can be invoked; they are not declared. 

Read Section 2, "Accessing the Interpretive Interface," for a detailed explanation of how 
to access the library and how to invoke the entry points. 

Renaming Entry Points witliin an Application Program 

The DMINTERPRETER library symbolic file, DATABASE/DMINTERPRETER, 
contains the names by which the interpretive interface expects the entry points to be 
called. These are the exported names. DATABASE/DMINTERPRETER is part of the 
release tape. 

ALGOL exported entry point names begin with ALGOL, for instance, ALGOLFTND. 
FORTRAN?? exported entry point names begin with FORTRAN??, such as 
F0RTRAN?7FIND. By using the ACTUALNAME clause of their library declaration, 
ALGOL and FORTRAN?? application programs can rename exported entiy points 
within the program. 

Refer to the Section 2, ''Accessing the Interpretive Interface," for the specifics of 
renaming entry points. 

COBOL esqported entry point names always begin with the prelBx DB, for example, 
DBFIND. Application programs written in any of the supported COBOL languages 
cannot rename entry points. 

Example of Renaming an Entry Point 

In this ALGOL program fi*agment, ALGOLFIND is renamed as MYFEND. MYFIND is an 
internal name that is used only within the application pn^am. The name of the entry 
point in the DMI library remains ALGOLFIND. 

LIBRARY DMI; 

BOOLEAN PROCEDURE MYFIND (DIRECTION, STRUCTURE, CONDITION) ; 
STRING DIRECTION, STRUCTURE, CONDITION; 
LIBRARY DMI (ACTUALNAME = "ALGOLFIND"); 
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Using Parameters in Entry Points 

Regardless of the application langug^e, each entry point uses the same number of 
parameters, has the same required parameters, and requires input in the same order. 
For instance, the entry point to move a nimieric value to a variable has three reqiured 
parameters. In aU languages, you enter the name of the structure first, the name of the 
item second, and the name of the variable third. 

While the data type of the same parameter might vary among the different languages, 
the parameter contains the same information. For example, a parameter might be a 
string in ALGOL, a display in COBOL, and a character in FORTRAN??. 

Basic syntax dis^ams describii^ the internal format of the entry point parameters 
are provided in Sections 3 through 6 with individual entry point descriptions for each 
language. The syntax and semantics of the parameters for each entry point are very 
similar to those for the corresponding language extension. Behavioral differences 
between DMINTERPRETER entry points and langus^e extensions are described in the 
text. 



Returning Exceptions 

DMSn software evaluates each call to a DMINTERPRETER entry point. If the call 
cannot be successfully or correctly completed, DMSII returns an exception word to the 
program. 

The exception handling entry points use the DMSUPPORT library to interpret and 
report the exceptions. Read Section 5, "Handling Exceptions," for details of the 
exception handling entry points. 



Programming Considerations for the Interpretive 
Interface Only 

The foUowing guidelines apply to the interpretive interface only. They explain how to 
sequence entry points and how to code your program. Consult the DMSII Application 
Programming Guide for more extensive programming guidelines for both the 
interpretive int^ace and the language ext^ision interface. 

How you sequence the DMINTERPRETER entry points within your application program 
can determine how efficiently you access, manage, and manipulate the database. Your 
choice of application programming language, your choice of entry points, and your style 
of coding can reduce run-time overhead. 
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Sequencing Entry Points 



The interpretive interface is designed to provide a record-at-a-time interface to a 
database. For programming efficiency, use the following guidelines: 

• Locate records by using the DBFIND standard entry point. Examine the values of 
each item by using the appropriate DBGET data transfer entry point. 

• Add a new record to the database by first calling the DBCREATE standard entry 
point. Then use the appropriate DBPUT data transfer entry point to move the 
values of each item into the user work area. Finally, store the record by calling the 
DBSTORE standard entry point. 

• Modify a record by first calling the DBLOCK standard entry point to locate it. Then 
call the appropriate DBPUT data transfer entry points to alter the values of the 
items. Use the DBSTORE standard entry point to store the modified values. 

• Remove a record from the database by calling the DBDELETE standard entry point. 



When accessing the interpretive interface, follow these recommendations to reduce 
run-time overhead: 

• Whenever possible, write application programs in ALGOL. 

Because ALGOL programs directly call the entry points that perform the functions 
of the interpretive interface, they markedly reduce run-time overhead. 

• In ALGOL, tise preinitialized string variables instead of string expressions as 
parameters. Doing so eliminates the need to allocate string temporaries in the 
calling procedure. 

• Use consecutive caUs to minimize structure-switching overhead. 

The DMLNTERPEETER library remembers the last structure on which it operated. 
Therefore, you can reduce structure-switching overhead if calls on one structure are 
not interspersed with calls on another structure. 

• Minimize the use of blanks. 

Avoid passing unnecessary blanks to the interpretive interface. To eliminate 
the unnecessary blanks, allocate string temporaries and make calls to additional 
procedures. ^ 

The following example shows code with unnecessaxy blanks: 

DBSTORE (" DS" ) 
The interpretive interface processes the following call faster: 

DBSTORE ("DS") 

Note: Do not eliminate all blanks. Indttde blanks where they make your 
code more readable. Always include required blanks. 

• UnconditionanycaUDBBBGEmANSACTION and DBENDTRANSACTION entry 
points. 



Reducing 



Run-Time Overhead 



1^ 
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DMSn software ignores DBBEGINTRANSACTION and DBENDTRANSACTION 
calls for unaudited databases. You can simplify application programs by 
imconditionally calling these entry points. The programs can then be run unaltered 
£^ainst an audited or imaudited database. 

• Use code-locking protocols within your application program. 

The DMINTERPRETER library stack uses global items to retain information 
between calls. Using global items greatly speeds up execution, but prevents 
multiprocessing. Thus, if the library declared by a parent task is visible to two or 
more offspring tasks, the offspring can receive unexpected results if they call the 
library simultaneously. 

Locking conventions within the DMINTERPRETER library can prevent imexpected 
results, but the locking conventions slow down execution speed. Consequently, when 
the library is visible to multiple offspring tasks, the application program should 
implement its own locking protocols. 

• Compile separate code files for each database. 

Do not use a database equation when accessing the DMINTERPRETER library. 
Instead, compile a separate DMINTERPRETER library code file for each database. 



8600 0155-000 



1-9 



8600 0155-000 



Section 2 

Accessing the Interpretive interface 



The DMSn interpretive interface works with any programming language that can import 
libraiy objects. This section, organized alphabetically by language, details the steps and 
syntax used in ALGOL, COBOL, and FOKTRAN77 application programs to access a 
DMINTEKPRETER library and its entry points. 



General Guidelines for Accessing the Interpretive 
Interface 



As you write your application program, consider the following factors: 

• Invoking or dedariag a DMSII database actually invokes or declares the associated 
DMINTERPRETER library. 

• Invoking or declaring a DMINTERPRETER library has two main purposes: 

- To make the names of the data items available to the application program 

- To perform syntax checking 

• Access to a database must be explicitly requested by opening the database. 

• Declaring an entry point makes the entry poiat available to the program. 

- In COBOL, invoking the database also declares the entry points. 

- In ALGOL and FORTRAN??, declaring the entry points is a separate 
programming step, 

• Invoking an entry point, also known as calling the entry point, causes the actual task 
to be performed at run time. 

• The ^bolic file DATABASE/DMINTERPRETER, supplied on the release tape, 
contains declarations of library entry points for each langua^. 

If you code your programs in COBOL, you cannot select a subset nor can you rename 

the entry points. 

If you code your programs in ALGOL or FORTRAN??, you can choose to 

- Declare all the entry points through the $INCLUDE compiler control option. 

- Select a subset of the entry points. 

- Rename the entry points. 

Read Sections 3 throi^ 6 for details of how to code each of the entry points. 
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Accessing the Interpretive Interface in ALGOL 
Programs 

Application programs written in ALGOL use a 3-step process to access the interpretive 
interface. The program code must 

1. Declare the DMINTERPRETEK library. 

2. Declare the entry points as Boolean procedures. 

3. Invoke the entry points. 

Declaring a DMINTERPRETER Library in an ALGOL Program 

ALGOL programs must link to a DMINTERPRETER library directly; the 
DMINTERPRETER library contains the procedures that are named in the EXPORT 
declaration. 

Use either the long or short form of the LIBRARY declaration to declare an identifier 
(ID) as the library ID. The TITLE attribute can be used to specify the object code file 
title of the library. Both the long and short form of the LIBRARY declaration are valid. 

You can declare a library in any block of your user program. The library and its entry 
points are vaUd only within the scope of the block. If you exit the block, the program is 
no longer linked to the library. 

The following syntax diagram shows the long form of the LIBRARY declaration: 
<library declaration> 

— LIBRARY — <library ID> — » 



^ L ( ^ TITLE — = — " — <EBCDIC stnng> — " ^ _ J" ^ ' 
Use the following syntax for the short form of the LIBRARY declaration: 
<library declaration> 

<library ID>.TITLE:="<EBCDIC string>"; 

As shown in the following syntax diagram, a library identifier is an ALGOL identifier. 
<iibrary ID> 

— <i dent i f i er> 1 
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The variable elements of the diagrams are e^lained as follows: 



Element 



Explanation 



<library ID> 



An internal name within the application program used to refer to the 
DMINTERPRETER library. 



<identifier> 



Any sequence of characters beginning with a letter and consisting of 
letters, digits, hyphens (-), and underscores (_). 



< EBCDIC string> 



A connected group or sequence of EBCDIC characters, excluding double 
quotation marks ("). 



In the long form, the EBCDIC string must have a period (.) as its last 
character and must be a properly formed file title. 



In the short form, the EBCDIC string need not have a period as the last 
character. 



Consult the ALGOL Reference Manual, Vol. 1 for detailed information on libraries, the 
EXPORT declaration, and the LIBEARY declaration. 

Examples of ALGOL Linkage to a DMINTERPRETER Library 

The following LIBRARY declaration specifies DMI as the library ID: 
LIBRARY DMI; 

In the next example, the TITLE attribute assigns the external name 
DMINTERPRETER/EMP JOB to the library ID. Because the example shows the long 
form of the declaration, the EBCDIC string has a period as its last character. 

LIBRARY DMI (TITLE="DMINTERPRETER/EMPJOB.") ; 

The next example shows the short form of LIBRARY declaration. Again, the library ID 
is DMI and the external name is DMINTERPRETER/EMP JOB. Note that the EBCDIC 
string does not have a period as its last character. 

DMI.TITLE:= " DMINTERPRETER/EMP JOB" ; 



Declaring ALGOL Entry Points as Boolean Procedures 

In ALGOL, you must declare each entry point of a DMINTERPRETER library as a 
Boolean procedure. Youcandedaretheentrypointsinoneof two ways: 

• Use the declaration of the DMINTERPRETER libraxy and the ALGOL entiy points 
contained on the release tape. 

• Individually declare the entry points in your application program. 
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Using the Release Tape to Declare ALGOL Entry Points 

The DATABASE/DMINTERPRETER symbolic ffle provided on the release tape contains 

• A declaration oftheDMINTERPRETER library 

• Declarations of the ALGOL entry points 

• Type declarations for the entry points 

To incorporate all these declarations in your application program, use the $INCLUI)E 
compiler control option and specify the sequence range 20100000 through 20199999 
within the DATABASE/DMINTEEPRETER symbolic file. All the ALGOL entry points 
in the library are exported. 

On the release tape, the library identifier ^ DMI. The exported names of the entry 
points are declared and renamed with the prefix DB. Table 2-1 lists the exported name of 
each entry point, the type of the entry point, and how it is renamed. 



Table 2-1. ALGOL Entry Points 



Exported Name 


Type 


Renamed As 


ALGOLABORTTRANSACTION 


Standard 


DBABORTTRANSACTION 


ALGOLBEGINTRANSACTION 


Standard 


DBBEGINTRANSACTION 


ALGOLCANCELTRPOINT 


Standard 


DBCANCELTRPOINT 


ALGOLCLOSE 


Standard 


DBCLOSE 


ALGOLCREATE 


standard 


DBCREATE 


ALGOLDATA 


Data transfer 


DBDATA 


ALGOLDELETE 


Standard 


DBDELETE 


ALGOLEN DTRANSACTION 


standard 


DBENDTRANSACTION 


ALGOLEXCEPTIONNAME 


Exception handling 


DBEXCEPTIONNAME 


ALGOLEXCEPTIONTEXT 


Exception handling 


DBEXCEPTIONTEXT 


ALGOLFIND 


Standard 


DBFIND 


ALGOLFREE 


Standard 


DBFREE 


ALGOLFREESTR 


Standard 


DBFREESTR 


ALGOLGETBOOLEAN 


Data transfer 


DBGETBOOLEAN 


ALGOLGETDOUBLE 


Data transfer 


DBGETDOUBLE 


ALGOLGETKANJI 


Data transfer 


DBGETKANJI 


ALGOLGETREAL 


Data transfer 


DBGETREAL 


ALGOLGETSTRING 


Data transfer 


DBGETSTRING 


ALGOLLOCK 


Standard 


DBLOCK 



continued 
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Table 2-1. ALGOL Entry Points (cont.) 



Exported Name 


Tvoe 


Renamed As 




oLanQaiU 


UDLUUi\o 1 rv 




Of SI riHa rrl 
dial Ida lU 




Al ftni PI ITROni PAM 
MLvaULrU 1 DUULC/MN 


uaia iransTcr 


HRPI ITRHOI FAM 
UDrU 1 DUULLMIN 


Al fif\\ Dl ITnr>l IRI C 
MLvaULrU 1 UUUDLC, 


Udia iransrer 


rtRPI ITnni IRI C 
UDrU 1 UUUDLC. 


Al ftOI P! ITI^AM II 
MLvaULrU 1 rVMINJI 


Udia iransrer 


HRPI ITl^ AM II 
UDrU 1 INMINJI 


ALGOLPUTNUI L 




DRPIJTNIJI 1 


ALGOLPUTREAL 


Data transfer 


DBPUTREAL 


ALGOLPUTSTRING 


Data transfer 


DBPUTSTRING 


ALGOLRECREATE 


Standard 


DBRECREATE 


ALGOLSAVETRPOINT 


Standard 


DBSAVETRPOINT 


ALGOLSECURE 


Standard 


DBSECURE 


ALGOLSECURESTR 


Standard 


DBSECURESTR 


ALGOLSET 


Standard 


DBSET 


ALGOLSETLIMIT 


Attribute setting 


DBSETLIIVIIT 


ALGOLSTATUS 


Exception handling 


DBSTATUS 


ALGOLSTORE 


Standard 


DBSTORE 


ALGOLVERB 


Standard 


DBVERB 



A table comparic^ the types of entry points (standard, data transfer, exception handling, 
and attribute setting) appears under "Identifying the Four Types of DMINTERPKETER 
Entry Points** in Section 1. The function and coding for each entry point are detailed in 
Sections 3 through 6. 

Using a Procedure Declaration for ALGOL Entry Points 

Individiialfy declare entry points in a procedure declaration if you want to 

• Declare a subset of the entry points. 

• Rename the entry points. 

Declaring a Subset of ALGOL Entry Points 

If you use the $INCLUDE option, all ALGOL entry points in the library are exported. 
However, in some instances, your program oiify needs a few or selected entry points. In 
these cases, to improve processing time, declare each individual entry points in separate 
procedure declarations rattier than export all the entry points. . 
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Renaming ALGOL Entry Points 



Unless specifically renamed, a library entry point is exported (accessed by the ALGOL 
program) by its name in the DATABASE/DMINTERPRBTER symbolic file. The 
ACTUALNAME clause in a procedure declaration lets you rename a libraiy entry point. 



Coding ALGOL Procedure Declarations 

Use the procedure declaration to declare individual library entry points in an ALGOL 
program. The procedure identifier, given in the procedure heading, links to the 
appropriate entry point given in the ACTUALNAME clause. The following diagram 
shows the syntax of the procedure declaration: 

<library entry point declaration> 

— "sprocedure heading> — ; — LIBRARY — ^library ID> » 



L ( — ACTUALNAME — = — " — <EBCDIC string> —" — )-' 



<procedure heading> 



cprocedure ID>- 



L-<formal parameter part>-J 



Each variable element in the procedure declaration is explained as follows: 
□ement Explanation 

<procedure ID> A unique sequence of characters beginning with a letter and consisting of 
letters, digits, hyphens (-}, and underscores (_} that identify the 
procedure. The identified procedure cannot be dieclared FORWARD or 
EXTERNAL 

<formal A list of items to be passed as parameters when the procedure is 

parameter part> invoked. 

<library ID> An internal name within the application prc^ram used to refer to the 

DMINTERPRETER library. The library ID must be previously declared in 
an available LIBRARY declaration. 

< EBCDIC string> The actual name that is given for this procedure in the template of this 
library. The name is given as a connected group of EBCDIC characters, 
excluding the quotation marks("}. 

In the ACTUALNAME clause, the EBCDIC string cannot contain any 
leading, trailing, or embedded blanks and must be a valid ALGOL 
identifier. 

Example of Declaring and Renaming an Entry Point in ALGOL 



Thk example shows how an entry point can be declared within an ALGOL program. The 
LIBRARY declaration gives DMI as the library ID. The LIBRARY declaration is followed 
by the two-part LIBRARY entry point dedaratioi^ the procedure dedaratiion and the 
library notation. 
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The Boolean procedure declaration names the entry point DBOPEN and defines its 
parameter, OPENTYPE, as a string. The next LIBRABY declaration tells the application 
program to use the procedure ALGOLOPEN in the DMI library every time DBOPEN 
is invoked. For this program only, ALGOLOPEN is renamed as DBOPEN. The actual 
name of the entry point in the library remains ALGOLOPEN. 

LIBRARY DMI; 

BOOLEAN PROCEDURE DBOPEN (OPENTYPE); 
STRING OPENTYPE; 

LIBRARY DMI (ACTUALNAME="ALGOLOPEN") ; 

Invoking ALGOL Entry Points 

Once you have declared a DMINTERPRETER library and its entry points in your 
ALGOL application program, you can invoke any dedared entry point as a Boolean 
procedure. 

After an entry point call on the DMINTERPRETER library, a result descriptor is 
returned as a Boolean value. This result descriptor is a 48-bit word, which is the 
standard DMSn exception word. It includes the exception category and subcategory, 
and the structure number. 

When a call on the DMINTERPRE'EER library causes an exception, the last bit in the 
48-bit word is set to 1. When a caU on the library is successful, the 48-bit word contains 
all zeros. 

Content of Exception Word Meaning 

0 The call was successful. 

1 An exception occun^ed. 

For more information on exceptions, refer to Section 5, ''Handling Exceptions.'' 

lypical Method for Invoking an ALGOL Entry Point 

The following is a typical method for invoking an ALGOL entry point, where RSLT 
is a Boolean variable, DBOPEN is the renamed entry point ALGOLOPEN, and 
EXCEPTIONHANDLER is a procedure for handling exceptions; 

RSLT:=DBOPEN (OPEN__TYPE) ; 
IF RSLT 

THEN EXCEPTIONHANDLER; 
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Accessing the Interpretive Interface in COBOL 
Programs 

Application programs witten in any of the supported COBOL languages use a 2-step 
process to access the interpretive interface. The program code must 

1. Change the TITLE attribute of the DMINTEEPRETER library. 

2. Livoke the entry points through a CALL statement. 

Consult volume 1 of the appropriate COBOL reference manual for details of COBOL, 
COBOL74, and COBOL85 syntax. 

Exported Names of COBOL Entry Points on the Release Tape 

The DATABASE/DMINTERPRETER symboMc file provided on the release tape contains 
the exported names of the COBOL entry points. You cannot explicitly declare or rename 
any library entry point. Table 2-2 lists ithe type and exported name for each entry point. 

Note: The parameters for COBOL entry points are translated into 

parameters that are compatible with ALGOL, The ALGOL entry 
points within the DMINTERPRETER library perform the actual 
operations against the database. 



Table 2-2. COBOL, C0B0L74, and C0B0L85 Entry Points 



Type 


Exported Name 


Standard 


DBABORTTRANSACnON 


Standard 


DBBEGINTRANSACTION 


Standard 


DBCANCELTRPOINT 


Standard 


DBCLOSE 


Standard 


DBCREATE 


Data transfer 


DBDATA 


Standard 


DBDELETE 


Standard 


DBENDTRANSACTION 


Exception handling 


DBEXCEPTIONNAME 


Exception handling 


DBEXCEPTIONTEXT 


Standard 


DBFIND 


Standard 


DBFREE 


Standard 


DBFI^EESTR 



continued 
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Table 2-2. COBOL, C0B0L74, and COBOL85 Entry Points (cont.) 



Type 


Exported Name 


Data tran^pr 


DBGETBOOLEAN 


L^Q LCI LiailOld 


DBGETDISPLAY 




DBGETDOUBLE 


L/CllCI lICIIIOlCi 




natfl tran^fpr 

L^CILCI llullOld 


DBGETREAL 


eta nHfl rrl 


DBLOCK 


Ctanrlarrl 


DBl OCKSTR 


oLaiiuciiu 


DBOPEN 


Hatfl tran^fpr 

L/uLCl LiailOld 


DBPUTBOOLEAN 


DstA trsincfpr 
uoiio uaiidici 


DRPUTniSPL AY 


Dsta tran^pr 

l^Ota LICIIIdId 


DBPUTDOUBLE 


Data transfer 


DBPUTKANJI 


Data transfer 


DBPUTNULL 


Data transfer 


DBPUTREAL 


Standard 


DBRECREATE 


Standard 


DBSAVETRPOINT 


Standard 


DBSECURE 


Standard 


DBSECURESTR 


Standard 


DBSET 


Attribute setting 


DBSETLIMIT 


Exception handling 


DBSTATUS 


Standard 


DBSTORE 


Standard 


DBVERB 



A table comparing the types of entry points (standard, data transfer, exception handling, 
and attribute setting) appears under ""Identifying the Four I^ypes of DMINTEBPBETER 
Entay Points" in Section 1. The function and coding for each entry point are detailed in 
Sections 3 through 6. 

Using the COBOL CHANGE Construct to Invoke a DMINTERPRETER 
Library 

To invoke the DMINTBKPRETER library m COBOL application programs, use the 
CHANGE construct to change the TITLE attribute of the library to the actual name of 
the library code file. 
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The CHANGE construct changes the library ID to an identifier or a nonnumeric literal 
within the application program. Every time the program makes a call on the library 
ID, the call is directed to the library whose name corresponds to the identifier or the 
nonnumeric literal The following syntax diagram shows how to code the CHANGE 
construct: 



CHANGE Construct 

— CHANGE — ATTRIBUTE 



TITLE -r- OF -1- 
L IN -I 



ilibrary ID>— " — TO 



»-T— <i dent 1 f 1 er> p 

i— <nonnumeri c literal>— ' 



Each variable element of the CHANGE construct is explained as follows: 
Element Explanation 



<library ID> 



<iclentifier> 



< nonnumeric 
literal > 



The file name of the library to be called. The file name can be composed 
of letters, numbers, hyphens (-), underscores (_), and slashes (/). The 
library ID, including slashes, is used as the title of the library. 

If the library ID does not contain slashes, the entire name can be used as 
the internal name (INTNAME) for the library. 

If the library ID contains slashes, then the identifier that follows the last 
slash is used as the internal name (INTNAME) for the library. 

A data-name followed by the syntactically correct combination of 
qualifiers, subscripts, and indexes needed to uniquely reference the data 
item. 

A character string bounded by double quotation marks ("). The string can 
include any character in the character set of the computer. (To represent 
a single quotation mark character, use two single contiguous quotation 
marks. To represent a double quotation mark, use three single 
contiguous quotation marks.) 



Example of COBOL Linkage to a DMINTERPRETER Library 

This example changes the library identifier DMINTERPRETER to the identifier 
DMI-NAME. Within the program, all references to the library are to DMI-NAME. 

***Declanng the Identifier 

01 DMI-NAME PIC X{24) VALUE IS "DMINTERPRETER/EMPJOB". 

***Linking to DMINTERPRETER library 

CHANGE ATTRIBUTE TITLE OF "DMINTERPRETER" TO DMI-NAME. 
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Invoking COBOL Entry Points 

Use a CALL noimumeric literal statement to invoke entry points to the 
DMINTEKPRETER library. The CALL statement passes the required parameters in 
a USING clause and receives a result in a GIVING clause, as shown in the following 
syntax: 



<call nonnumeric literal statement> 

— CALL — " — <procedure ID>-t- IN — r-<1ibrary IDs 

L- OF -J 



3 



USING 



data -name 



L 



GIVING <data-name> 



The variable elements of the CALL statement are explained as follows: 
Element Explanation 
< procedure ID> Name of the procedural entry point. 

<library ID> The file name of the library to be called. The file name can be composed 

of letters, numbers, hyphens (-), underscores (J, and slashes (/). 

<data-name> In the USING clause, the name of the entry point to the 

DMINTERPRETER library. 

In the GIVING clause, the name of the variable where the result of the 
call is stored. 

Refer to Sections 3 through 6 for examples and detailed explanations of how to use the 
required parameters for each entry point. 



Passing Parameters with tlie USING Clause in COBOL 

Although parameters for the standard entry points and for most of the data transfer 
entry points are declared as the same type and at the same level for all COBOL 
languages, there are some dififerences: 

• Standard entry points and most data transfer entry points in all COBOL languages 
are DISPLAY items declared at level 01. 

• In COBOL, the following data transfer entry points must be declared as COMP-4 or 
COMP-5 items at level 77. In COBOL74 and COBOL85, they must be declared as 
REAL or DOUBLE items at level 77. 

DBGETREAL DBPUTREAL 
DBGETDOUBLE DBPUTDOUBLE 



8600 0155-000 



2-11 



Accessing the Interpretive Interface 



Exception Handling with the GIVING Clause in COBOL 

After a call on an entry point of the DMEN TJURPRETER library, a result descriptor is 
retiirned as an integer into the result variable identified in the GIVING clause. The 
returned integer is either 0 or 1, as shown in the following table. 

Returned Integer Meaning 

0 The call was successful. 

1 An exception occurred. 

For COBOL, the result variable must be a COMP-2 item declared at level 01. For 
COBOL74 and COBOL85, the result variable must be a COMP item declared at level 01. 

If an exception occurs, the program must then call the exception handling entry points. 
For more information on exceptions, refer to Section 5, "Handling Exceptions." 

Typical Method for Invoking a COBOL Entry Point 

The following example invokes the COBOL entry point DBCREATE in the 
DMINTERPRETER library. Two parameters are passed: one in the variable 
DATA-SET-NAME and one in the variable SPACE-1. The result descriptor is returned 
in the variable PJESULT. 

01 DATA-SET-NAME PIC X(17) VALUE IS "EMP". 

01 SPACE-1 PIC X(l) VALUE IS " 

CALL "DBCREATE OF DMINTERPRETER" 

USING DATA-SET-NAME, SPACE-1 
GIVING RESULT. 

Accessing the Interpretive Interface in FORTRAN77 
Programs 

Application programs written in FORTRAN?? use a 3-step process to access the 
interpretive interface: 

1. Declare the DMINTERPRETER library. 

2. Declare the entiry points as logical fimctions. 

3. Invoke tiie enliy points. 

Your FORTRAN?? program must explicit^ declare a DMINTERPi^TER library and 
each ofthe DMINTERPRETER library entry points that will be used. The declarations 
must appear once only, in the BLOCK GLOBALS subprogram. You must include the 
type declarations in every subprogram within the program. 



2-12 



8600 0155-000 



Accessing the Interpretive Interface 



Declaring a DM INTERPRETER Library in FORTRAN?? Programs 

FORTRAN?? programs must link to a DMINTERPRETER library directly; the 
DMINTERPRETER library contains the named functions. 

Use the LIBRARY statement to declare a symbolic name as the library ID. You can use 
the TITLE attribute to assign the external name of the library code file to the library ID. 
Then, within the application program, you can use the library ID as an internal name of 
the DMINTERPRETER library 

In FORTRAN?? programs, libraries are declared in a BLOCK GLOBALS subprogram. 
Each program has only one BLOCK GLOBALS subprogram. The subprogram must 
precede all other source statements. The subprogram is initiated by a BLOCK 
GLOBALS statement and terminated by an END statement. 

Consult the FORTRAN!! Reference Manual for more information on direct linkage, 
BLOCK GLOBALS subprograms, and the LIBRARY statement. 

The following diagram gives the syntax of the FORTRAN?? library statement: 
<library statement> 



— LIBRARY — <library ID^-i r 

L- ( — TITLE — = — <string^ ) -J 



<library ID> 

— <symbolic name>- 



Eadhi variable element in the library statement is explained as follows: 
Element Explanation 

<library ID> An internal name within the application prc^ram used to refer to the 

DMINTERPRETER library. 

<symbolic A sequence of from 1 to 31 letters, digits, underscores (_), or the dollar 

name> sign ($) that identifies the intemal name of a DMINTERPRETER library. 

The first character must be either a letter or the dollar sign ($}. 

<string> Name of the library code file. The string can consist of no more than 

255 characters, terminated by a period (.). The string must be delimited 
with an apostrophe (') or double quotation mark ("). An empfy string is 
not allowed. 

Note: Any input record that begins with a dollar sign ($) in column 1 or 
column 2 is treated as a compiler control image. If your program 
code has a symbolic name that begins with a dollar sign and starts in 
column 1 or column 2, your program will not compile suaxssfully. 
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Example of FORTRAN?? Linkage to a DMINTERPRETER Library 

The following code shows how the LIBKARY statement is used in a BLOCK GLOBALS 
subprogram. The library ED is DMI. The TITLE attribute is used to assign the external 
name DMINTERPRETEK/EMP JOB to the library ID. 

BLOCK GLOBALS 

LIBRARY DMI(TITLE="DMINTERPRETER/EMPJOB.") 
END 

Declaring FORTRAN77 Entry Points as Logical Functions 

In FORTRAN??, you must declare each entry point of a DMINTERPRETER library as a 
logical fimction. You can do so in one of two ways: 

• Use the declaration of the DMINTERPRETER library and the FORTRAN?? entry 
points contained on the release tape. 

• Individually declare the entry points in your application program. 

Using the Release Tape to Declare FORTRAN?? Entry Points 

The DATABASE/DMINTERPRETER symbolic ffle provided on the release tape contains 

• A declaration of the DMINTERPRETER library 

• Declarations of the FORTRAN?? entry points 

• Type declarations for the entry points 

To incorporate these declarations in your application programs, use the $INCLUDE 
compiler control option and specify the following sequence ranges within the 
DATABASE/DMINTERPRETER symbolic ffle: 

Declaration Sequence Range 

Library entry point declaration 20200000 tlirough 20249999 
Type declaration 20290000 through 20299999 

All the FORTRAN?? entry points in the library are exported. 

On the release tape, the library identifier is DME. The exported names of the entry 
points are declared and renamed with the prefix DB. Table 2-3 lists the exported name of 
each entry poiQt, the type of the entry point, and how it is renamed. 
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Table 2-3. F0RTRAN77 Entry Points 



Exported Name 


Type 


Renamed As 


F0RTRAN77AB0RTTRANSACTI0N 


Standard 


DBATR 


F0RTRAN77BEGINTRANSACTI0N 


Standard 


DBBTR 


F0RTRAN77CANCELTRP0INT 


Standard 


DBCNCL 


F0RTRAN77CL0SE 


Standard 


DBCLOSE 


F0RTRAN77CREATE 


Standard 


DBCR 


F0RTRAN77DATA 


Data transfer 


DBDATA 


F0RTRAN77DELETE 


Standard 


DBDEL 


F0RTRAN77ENDTRANSACTI0N 


Standard 


DBETR 


F0RTRAN77EXCEPTI0NNAME 


Exception handling 


DBEXCN 


F0RTRAN77EXCEPTI0NTEXT 


Exception handling 


DBEXCT 


F0RTRAN77FIND 


Standard 


DBFIND 


F0RTRAN77FREE 


Standard 


DBFREE 


F0RTRAN77FREESTR 


Standard 


DBFSTR 


F0RTRAN77GETCHARACTER 


Data transfer 


DBG ETC 


F0RTRAN77GETD0UBLE 


Data transfer 


DBGETD 


F0RTRAN77GETKANJI 


Data transfer 


DBGETK 


F0RTRAN77G ETLOGICAL 


Data transfer 


DBGETL 


F0RTRAN77GETREAL 


Data transfer 


DBGETR 


FORTRAN77LOCK 


Standard 


DBLOCK 


F0RTRAN77L0CKSTR 


Standard 


DBLSTR 


F0RTRAN770PEN 


Standard 


DBOPEN 


F0RTRAN77PUTCHARACTER 


Data transfer 


DBPUTC 


F0RTRAN77PUTD0UBLE 


Data transfer 


DBPUTD 


F0RTRAN77PUTKANJI 


Data transfer 


DBPUTK 


F0RTRAN77PUTL0GICAL 


Data transfer 


DBPUTL 


F0RTRAN77PUTNULL 


Data transfer 


DBPUTN 


F0RTRAN77PUTREAL 


Data transfer 


DBPUTR 


F0RTRAN77RECREATE 


Standard 


. DBRCR 


FORTRAN77SAVETRPOINT 


Standard 


DBSAVE 


F0RTRAN77SECURE 


Standard 


DBSEC 


F0RTRAN77SECURESTR 


Standard 


DBSSTR 



continued 
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Table 2-3. FORTRAN?? Entry Points (cont.) 



Exported Name 


Type 


Renamed As 


FORTRAN77SET 


Standard 


DBSET 


F0RTRAN77SETLIMIT 


Attribute setting 


DBSETL 


F0RTRAN77STATUS 


Exception handling 


DBSTAT 


F0RTRAN77ST0RE 


Standard 


DBSTORE 


FORTRAN77VERB 


Standard 


DBVERB 



A table comparing the types of entry points (standard, data transfer, exception handling, 
and attribute setting) appears under "Identifying the Four Types of DMINTERPRETER 
Entry Points" in Section 1. The fimction and coding for each entry point are detailed in 
Sections 3 through 6. 

Using the Logical Function for FORTRAN?? Entry Points 

Individually declare entry points if you want to do the following: 

• Declare a subset of the FORTRAN?? entry points. 

• Rename the FORTRAN?? entry points. 

To individually declare entry points, you need to use the LOGICAL FUNCTION library 
entiy point declaration, type statements, and the IN LIBRARY statement. The entry 
point declaration and IN LIBRARY statement are explained in the following text. For 
specific information about type statements, consult the FORTRAN?? Reference Manual. 



Declaring a Subset of the FORTRAN?? Entry Points 

If you use the $INCLIIDE option, all FORTRAN?? entry points in the library are 
exported. However, in some instances, your program only needs a few or selected entry 
points. In these cases, to improve processing time, declare the individual entry points 
rather than export all the entiy points. 



Coding the FORTRAN?? Library Entry Point Declaration 

The LOGICAL FUNCTION library entry point declaration identifies the entry point and 
parameters. The following diagram shows the syntax of the declaration: 

<library entry point declaration> 

— LOGICAL FUNCTION — <1ogica1 function name> — ( -Cpareunetel^^ ) -\ 
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Each variable element in the LOGICAL FUNCTION is explained as follows: 
Element Explanation 

< logical function A unique name that identifies the entry point in the library 
name> 

<parameter> A list of items to be passed as parameters when the entry point is 

invoked 

You must give the data type for each parameter in a type statement. For example, 
the following type statement identifies the data type of the parameter OTYPE as a 
character: 

LOGICAL FUNCTION DBOPEN (OTYPE) 
CHARACTER OTYPE 

The type statements must inmiediately follow the LOGICAL FUNCTION and must 
precede the IN LIBRARY statement. 



Renaming FORTRAN?? Entry Points 

Unless spedfically renamed, a library entry point is e^orted (accessed by the 
FORTRAN?? program) by its name in the DATABASE/DMINTERPRETER symbolic 
file. The ACTUALNAMB clause in an IN LIBRARY statement allows you to rename a 
library entry point. 



Coding a FORTRAN?? IN LIBRARY Statement 

The IN LIBRARY statement associates the logical function name (given in the library 
entry point declaration) with the library identifier. The ACTUALNAME clause allows 
you to rename the library entry point. The following diagram shows the syntax of the 
statement: 

<in library statement> 

— IN LIBRARY — <library ID:—, | 

L ( — ACTUALNAME — = — <string>— ) -I 

Each variable element in the statement is explained as follows: 
Bement Explanation 

<library ID> A unique sequence of from 1 to 31 characters consisting of letters, digits, 

underscores (J, or the dollar sign ($) that identifies the symbolic name 
of the library. The first character must be either a letter or the dollar sign 
($). 

<string> The actual name given for this logical function in the template of the 

library. 

Note: Any input record that begins with a dollar sign ($) in column 1 or 
column 2 is treated as a compiler control image. If your program 
code has a symbolic name that begins with a dollar sign and starts in 
column 1 or column 2, your program will not compile successfully. 
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Example of Declaring an Entry Point in a FORTRAN77 Program 

The following example shows how an entry point might be declared within a 
FORTRAN?? program. The logical ftmction name is DBOPEN. Its one parameter, 
OTYPE, has a data type of character. The IN LIBRARY statement tells the application 
program to use the procedm'e FORTRAN??OPEN in the DMI library every time 
DBOPEN is invoked. For this program only, FORTRAN770PEN is renamed DBOPEN. 

This program must have a preceding LIBRARY statement in a BLOCK GLOBALS 
subprogram to declare the DMENTERPRETER library before declaring the library entry 
point. 

LOGICAL FUNCTION DBOPEN (OTYPE) 
CHARACTER OTYPE 

IN LIBRARY DMI (ACTUALNAME = "FORTRAN770PEN") 
END 



Invoking FORTRAN?? Entry Points 

Once you have declared a DMINTERPRETER library and its entry points in your 
FORTRAN?? application program, you can invoke any declared entry point using a 
logical assignment statement. 

After an entry point call on the DMINTERPRETER library, DMSII software evaluates 
the logical function and returns a logical value to a program-assigned variable. The 
variable contains the result of the call, a result descriptor. 

The result descriptor is a 48-bit word, which is the standard DMSII exception word. It 
includes the exception category and subcategory, as well as the structure number. When 
a call on the DMINTERPRETER library causes an exception, the last bit in the 48-bit 
word is set to 1. When a call on the library is successful, the 48-bit word contains all 
zeros. 

Content of Exception Word Meaning 

0 The caii was successfuL 

1 An exception occurred. 

For more information on exceptions, refer to Section 5, '^Handling Exceptions." 

Typical Method for Invoking a FORTRAN?? Entry Point 

The following is a typical method for invoking a FORTRAN?? entry point, where RSLT 
is a logical variable, DBOPEN is the renamed entxy point FORTRAN770PEN, and 
EXCEPT is a subroutine for handling exceptions: 

RSLT = DBOPEN (UPDATE) 
IF (RSLT) CALL EXCEPT 
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Standard entry points perform the standard database manipulation tasks, such as 
locating a record, beginning and ending transaction state, and storing records. 

Each standard database manipulation task with its corresponding entry points are listed 
in Table 3-1. Use the heading for each listed task to locate the pages that detail the 
entry point. For example, a description of the standard entry points ALGOLOPEN, 
DBOPEN, and FOKTRAN770PEN is found under "Opening a Database." The tasks 
are presented in the general order in which they are usually coded, starting with opening 
the database and ending with closing the database. General guidelines for using the 
standard entry points precede the task descriptions. 



Table 3-1. Standard Entry Points to the DMINTERPRETER Library by Task 



Task 


Entry Points 


Opening a database 


ALGOLOPEN 




DBOPEN 




F0RTRAN770PEN 


Creating reserve space for new records 


ALGOLCREATE 




DBCREATE 




FORTRAN77CREATE 


Setting tlie current patti 


ALGOLSET 




DBSET 




F0RTRAN77SET 


Explicitly freeing records 


ALGOLFREE 




DBFREE 




FORTRAN77FREE 


ExpGcftly freeing structures 


ALGOLFREESTR 




DBFREESTR 




F0RTRAN77FREESTR 


Finding records 


ALGOLFIND 




DBFIND 




F0RTRAN77FIND 



continued 
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Table 3-1. Standard Entry Points to the DMINTERPRETER Library t>y Tasic (cont.) 



Task 


Entry Points 


Locldng records 


ALGOLLOCK 
DBLOCK 

FORTRAN77LOCK 


Loclcing structures 


ALGOLLOCKSTR 

DBLOCKSTR 

F0RTRAN77L0CKSTR 


Securing records 


ALGOLSECURE 
DBSECURE 

FORTRAN77SECURE 


Securing structures 


ALGOLSECURESTR 

DBSECURESTR 

FORTRAN77SECURESTR 


B^in transaction— entering transaction state 


ALGOLBEGINTRANSACTION 

DBBEGINTRANSACTION 

FORTRAN77BEGINTRANSACTION 


Aborting transactions 


ALGOLABORTTRANSACTION 

DBABORTTRANSACTION 

FORTRAN77ABORTTRANSACTION 


Saving transaction points 


ALGOLSAVETRPOINT 

DBSAVETRPOINT 

FORTRAN77SAVETRPOINT 


Canceling transactions isacic to savepoints 


ALGOLCANCELTRPOINT 

DBSCANCELTRPOINT 

F0RTRAN77CANCELTRP0iNT 


Deleting data records 


ALGOI-DEI^E 

DBDELETE 

FORTRAN77DELETE 


Re-creating records 


ALQOLRECREATE 

DBRECREATE 

F0RTRAN77RECREATE 



continued 
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Table 3-1. Standard Entry Points to the DMINTERPRETER Library by Tasic (cent.) 



Task 


Entry Points 


Storing records 


ALGOLSTORE 




DBSTORE 




F0RTRAN77ST0RE 


End transaction— leaving transaction state 


ALGOLENDTRANSACTION 




DBENDTRANSACTION 




FORTRAN77ENDTRANSACTION 


Closir^ a database 


ALGOLCLOSE 




DBCLOSE 




F0RTRAN77CL0SE 


Executing language extensions 


ALGOLVERB 




DBVERB 




F0RTRAN77VERB 



The discussion of each task includes the following: 

• A brief explanation of the function of the entry point 

• Syntax diagrams and semantics that describe required parameters 

• Program fragments that illustrate 

- Declaringvariablesfor the entry points 

- Invoking the entry point 

- Returning results from the DMINTERPRETER library 

Unless specifically noted, COBOL, COBOL74, and COBOL85 have the same 
requirements. 

Guidelines for Using Standard Entry Points 

For ppftgramTning e£5ciency, use the following guidelines: 

• Always open the database e^licitly as the jQrst database operation. 

• Create and find records outside transaction state. 

• Make all data transfers outside transaction state. (Read Section 4, "Transf^ring 
Data," for details of transferring data using DBGET and DBPUT data transfer entry 
points.) 
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• Be-create a record immediately after deleting the base record and before any 
operation can alter the user work area. You can re-create the record either in or out 
of transaction state. 

• Enter transaction state to store and delete records. 

• Always esplidt](7 dose the database. 

Figure 3-1 illustrates the ideal flow for standard entry point operations in and out of 
transaction state. The figure emphasizes that you must declare (invoke) the database 
before using any entry point operation. The figure does not show how the flow is 
effected by the use of data transfer entry points, exception handling entry points, or the 
attribute setting entry point. 

Read Sections 4 through 6 for the syntax of data transfer entry points, exception 
handling entiy points, and the attribute setting entry point, respectively. Section 
2, "Accessing the Interpretive Interface," details how each language accesses the 
interpretive interface and how each language invokes an entiy point. 
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DECLARE or INVOKE 
database 



OPEN 
database 



^1 



CREATE record 




FIND record 


RECREATE record 


FREE record 


SECURE record 


FREE structure 


SECURE structure 


LOCK record 


SET current path 


LOCK structure 


No^ 


A 




Done > 







I 1 

Operations , 
Outside I 
Transacti on i 
State ' 
I I 




ABORT transaction RECREATE record 
CANCEL transaction point SAVE transaction point 
DELETE record STORE record 




I 1 

Operations . 
■ Inside > 
Transaction ■ 
State ' 
I I 



END 

TRANSACTION STATE 




CLOSE 
database 



Figure 3-1. Standard Entry Point Operations In and Out of Transaction State 



8600 0155-000 



3-5 



Opening a Database 



Opening a Database 

An open operation establishes the way in which the program accesses data values and 
performs database operations. 

• Inquiry access allows the program to retrieve data but not add, delete, or alter data. 

• Update access allows the program to retrieve and manipulate data. 

You must explicitly open the database before performing any database operation. Until 
the database is explicitly opened, any call on a standard entry point, data transfer 
entry point, or attribute setting entry point results in an error. However, whether the 
database is opened or closed, your program can call the exception handling entry points 
and perform operations on the intrinsic data set DBSTRUCTUEE. 

To reduce system overhead, open each database only once in any given program 
execution. 

Passing a Parameter 

The standard entry point used to open the database has one required parameter — open 
disposition: 

Parameter Explanation 

<open Determines the access mode— whether the datat)ase is opened for 

disposition> inquiry (read-only) or for both inquiry and updates 

Note that the you do not pass the name of the database to the entry point. The entry 
point assumes you want to open the most recently declared database. 

Table 3-2 gives the exported names of the entry points, along with the parameter and 
the data type of the parameter. 



Table 3-2. Opening a Database 







Data Type of 


Exported Name of Entry Point 


Parameter 


Parameter 


ALGOLOPEN 


<open disposition > 


STRING 


DBOPEN 


<open disposition > 


DISPLAY 


FORTRAN770PEN 


<open disposition > 


CHARACTER 
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The following syntax diagram shows that the open disposition parameter can set the 
access mode to one of two values: 

<open disposition> 

— P_ INQUIRY -1 1 

I- UPDATE — I 

The values of the open disposition parameter are explained as follows: 
Element Explanation 

INQUIRY Allows the program to retrieve data only; does not allow updates. Any 

request to add, delete, or alter records results in an exception condition. 

UPDATE Allows the program to retrieve data and to add, delete, or alter data. 

Programming Examples 

The following program fragments set the open disposition to INQUIRY. The database is 
open for both inquiries and updates. 

ALGOL Program Fragment 

%Declaring local variables 

STRING 

OPEN_TYPE; 
BOOLEAN 

RSLT; 

%Assigm'ng values to parameters 
OPEN_TYPE;="UPDATE"; 
%Declanng library entry point 
LIBRARY DMI; 

BOOLEAN PROCEDURE DBOPEN (OPENTYPE) ; 
STRING OPENTYPE; 

LIBRARY DMI (ACTUALNAME="AL60L0PEN") ; 

%Invoking entry point 

RSLT:=DBOPEN(OPEM_TYPE) ; 
IF RSLT 

THEN EXCEPTIONHANDLER; 
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C0B0L74 or C0B0L85 Program Fragment 

Note: In the following example, the variable RESULT is declared as 
a COMP item, making this example d COBOL74 or COBOL85 
program fragment. If RESULT were declared as a COMP-2 item, 
this fragment could be used in a COBOL program. 

***Declanng variables 

01 OPEN-TYPE PIC X(6) VALUE "UPDATE". 
01 RESULT PIC 9(1) COMP VALUE IS 0. 

***Invoking entry point 

CALL "DBOPEN OF DMINTERPRETER" 
USING OPEN-TYPE 
GIVING RESULT. 



FORTRAN?? Program Fragment 

***Library declaration for entry point 

LOGICAL FUNCTION DBOPEN (OTYPE) 
CHARACTER OTYPE 

IN LIBRARY DMI (ACTUALNAME = "F0RTRAN770PEN") 

END 

***Setting variables to initial values 

CHARACTER UPDATE *6 /"UPDATE"/ 

***Declaring local variables 

LOGICAL RSLT 

***Invoking entry point 

RSLT = DBOPEN (UPDATE) 
IF (RSLT) CALL EXCEPT 



3^ 
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Creating Reserve Space for New Records 

Adding a new record is a three-step operation: 

1. Reserve space in the user work area for the new record (using either 
ALGOLCKBATE, DBCREATE, or FORTRAN77CREATE). DMSn initializes the 
work area with null values for each item in the record. 

2. Move values from program-declared variables into the record using DBPUT data 
transfer entry points. (See Section 4, "Transferring Data.") 

3. Store the record into the database. (See "Storing Records" later in this section.) 

You can created new records both in and out of transaction state. You can transfer 
values both in and out of transaction state. However, your program must be in 
transaction state to store the record. For faster processing time, create new records and 
transfer values outside of transaction state. Then enter transaction state to store the 
record. 

Passing Parameters 

The standard entry point used to reserve space in the user work area has two required 
parameters: the data set qualified name and the record type. 

Parameter Explanation 

<data set Identifies the data set for the new record, 

qualified name> 

<record type> Determines whether the record has a variable or a fixed format. (The 

DMSII Technical Overview has a detailed explanation of variable 
and fixed-format records.) 

Table 3-3 gives the exported names of the entry points, along with the parameters and 
the data type of each parameter. 



Table 3-3. Creating Reserve Space for New Records 



Exported Name of Entry Point 


Parameter 


Data Type of 
Parameter 


ALGOLCREATE 


<data set qualified name> 


STRING 




< record type> 


STRING 


DBCREATE 


<data qualified name> 


DISPLAY 




< record type> 


DISPLAY 


F0RTRAN77CREATE 


<data set qualified name> 


CHARACTER 




< record type> 


CHARACTER 
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Creating Reserve Space for New Records (cont.) 



Data Set Qualified Name 

The data set name mxist be unique. The toUomDg syntax diagram shows you can use a 
maximum of 12 qualifying parameters to imiquely identify the data set: 



<data set qualified name> 

■ — <narae>- 



/12\ 



OF — <name> 

^ /12\ 

— <narae> 



The variable element < name > of the data set name is explained as follows: 
Element Explanation 

<name> Identifies tfie data set for tlie new record. 

Tlie name can consist of from 1 to 17 letters, digits, and -depending on 
the language— either underscores (_) or hyphens (-). The first character 
must be a letter. The last character must be either a letter or a digit. 

For example, if your program accesses two databases (DBl and DB2) and each database 
has a data set named CLASS, you must qualify the data set name by naming the 
database. 

Record Type 

Use the following syntax to specify the record type for the new record: 



<record type> 



-T— <i nteger> — 

h-<one or more blanlcs: 
'-<empty string> 



The variable elements of the record type are explained as follows: 



Element 

<int^er> 



one or more 
blanks 

empty string 



Explanation 

Creates a variable-format record. An int^er is a whole number 
(0123456789) that consists of 1 to 12 digits and whose maximum 
value can be 549755813887. 

A variable fbmiat consists of two parts: a fixed part (header) and a 
variable part (trailer). 

• Enter a nonzero int^r to create both parts of a variable-format 
record. 

• Enter a zero (0) to create only the fixed part of a variable-format 
record- 
Creates a fixed-format record. 

Creates a fixed-format record. 
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Programming Examples 

The following program fragments create a new fixed-formiat record for the data set EMP 
The data set name is imique and does not need any qualifying parameters. 



ALGOL Program Fragment 

%Declanng local variables 

STRING 

DATA_SET_NAME , SPACE_1 ; 
BOOLEAN 

RSLT; 

%Assign1ng values to parameters 

DATA_SET_NAME : = " EMP" ; 
SPACE_1:=" "; 

%Declaring library entry point 
LIBRARY DMI; 

BOOLEAN PROCEDURE DBCREATE (STRUCTURE. RECORDTYPE) ; 
STRING STRUCTURE, RECORDTYPE; 
LIBRARY DMI (ACTUALNAME="ALGOLCREATE") ; 

%Invoking entry point 

RSLT:=DBCREATE(DATA_SET_NAME,SPACE 1); 
IF RSLT 

THEN EXCEPTIONHANDLER; 



C0B0L74 or C0B0L85 Program Fragment 

Note: In the following example, the variable RESULT is declared as 
a COMP item, making this example a COBOL74 or C0B0LS5 
program fragment If RESULT were declared as a COMP-2 item, 
this fragment could he used in a COBOL program. 

***Declaring variables 

01 DATA-SET-NAME PIC X(17) VALUE IS "EMP". 

01 SPACE-1 PIC X(l) VALUE IS " 

01 RESULT PIC 9(1} COMP VALUE IS 0. 

★★★Invoking entry point 

CALL "DBCREATE OF DMINTERPRETER" 

USING DATA-SET-NAME, SPACE-1 
GIVING RESULT. 
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Creating Reserve Space for New Records (cont.) 



FORTRAN?? Program Fragment 

***Declan'ng library entry point 

LOGICAL FUNCTION DBCR (STR, RECTYP) 
CHARACTER STR, RECTYP 

IN LIBRARY DMI (ACTUALNAME = "F0RTRAN77CREATE") 
END 

***Setting variables to initial values 

CHARACTER DSNAME *4 /"EMP"/, 

* SPACE *1 /" V 

***Declaring local variables 

LOGICAL RSLT 

***Invoking entry point 

RSLT = DBCR (DSNAME, SPACE) 
IF (RSLT) CALL EXCEPT 
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Setting the Current Path 

As your program invokes a structure, the DMSIE software creates and maintains a 
current path for that structure. The current path points to the record in that structure 
your program is currently using. This record is known as the current record. 

You can position, or set, the current path of a data set to either the beginning or ending 
of the structure. The beginning of the structure is one record position before the first 
physical record. The end of the structure is one record position after the last physical 
record. 

You also can set the current path of an index set with the ALGOLSET, DBSET, and 
FORTRAN77SET entry points. The current point of an index set is positioned to the 
current record within the spanned data set. 

Passing Farameters 

The standard entry point used to set a current path has two required parameters: the 
name of a structure and a target location. 

Parameter Explanation 

<stmcture> Identifies either the data set or index set whose current path will be 

reset. 

<target> Identifies the location where the current path should point: the b^inning 

of the structure, the end of the structure, or, for an Index set, the current 
record in a particular data set. 

Table 3-4 gives the exported names of the entry points, along with the parameters and 
the data type of each parameter. 



Table 3-4. Setting the Current Path 



Exported Name of Entry Point 


Parameter 


Data Type of 
Parameter 


ALGOLSET 


<structure> 


STRING 




<target> 


STRING 


DBSET 


<structure> 


DISPLAY 




<target> 


DISPLAY 


F0RTRAN77SET 


<structure> 


CHARACTER 




<target> 


CHARACTER 
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Setting the Current Path (cont.) 



structure 

The structure can be either a data set or an index set. The name of the set must be 
unique. The following syntax diagram shows you can use a maximum of 12 qualifying 
parameters to uniquely identify the data set or index set: 



<structure> 

■ — r— <data set qualified name> — r 
<index set qualified name>-J 



<qualified name> 

— <r>ame>- 



/12\ 



OF — <name> 

^ /12\ 

— <nanie> 



The variable elements of the structure parameter are explained as follows: 



Element 

<data set 
qualified name> 

< index set 
qualified name> 

<name> 



Explanation 

Identifies the data set whose current path is repositioned at run time. 

identifies the index set whose current path is repositioned at run time. 

Identifies the name of the data set or index, set. A name can consist of 
from 1 to 17 letters, digits, and— depending on the language— either 
underscores (_) or hyphens (-), The first character must be a letter. The 
last character must be either a letter or a digit. 



For example, if your program accesses two databases (DBl and DB2) and each database 
has a data set named CLASS, you must qualify the data set name by naming the 
database. 

Target 

Use the following syntax to set the location target for the pointer: 



<target> 



—1- BEGINNING 
\- ENDING 



1— <data set qualified name? 



The variable elements of the target parameter are explained as follows: 
Element Explanation 

BEGINNING Sets the current path to the start of the file at run time. 

ENDING Sets the current path to the end of the file at run time. 

<data set Identifies the data set spanned by the index set and repositions the 

qualified name> pointer of the index set to the current record within the spanned date set. 
Valid only for index sets. 
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Setting the Current Path (cont.) 



Programming Examples 

In the program fragments, the data set EMP is set to its beginning point. 



ALGOL Program Fragment 

%Declanng local variables 

STRING 

DATA_SET_NAME; 
BEGIN_1; 

boolean"" 

RSLT; 

%Assigning values to parameters 

DATA__SET_NAME:="EMP"; 
BEGINJ:="BEGINNING"; 

%Declaring library entry point 

LIBRARY DMI; 

BOOLEAN PROCEDURE DBSET (STRUCTURE, TARGET) ; 
STRING STRUCTURE, TARGET; 
LIBRARY DMI (ACTUALNAME="ALGOLSET") ; 

%Invoking entry point 

RSLT : =DBSET (DATA_S ET_NAME . BEGI N_l ) ; 
IF RSLT 

THEN EXCEPTIONHANDLER; 



C0B0L74 or C0B0L85 Pmgtam Fragment 

Note: In this example, the variable RESULT is declared as a COMP item, 
making this example a COBOL74 or COBOL85 program fragment. 
If RESULT were declared as a COMP item, this fragment could be 
used as a COBOL program. 

***Declanng variables 

01 DATA-SET-NAME PIC X(17) VALUE IS "EMP". 

01 BEGIN-1 PIC X(9) VALUE IS "BEGINNING". 

01 RESULT PIC 9(1) COMP VALUE IS 0. 

*** Invoking entry point 

CALL "DBSET OF DMINTERPRETER" 

USING DATA-SET-NAME, BEGIN-1 
GIVING RESULT. 
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Setting the Current Path (cont.) 



F0RTRAN77 Program Fragment 

***Declaring library entry point 

LOGICAL FUNCTION DBSET (STR.TARGET) 
CHARACTER STR, TARGET 

IN LIBRARY DMI (ACTUALNAME = "F0RTRAN77SET") 

END 

***Setting variables to initial values 

CHARACTER DSNAME *4 /"EMP"/ 

CHARACTER BEGIN *4 /"BEGINNING"/ 

***Declaring local variables 

LOGICAL RSLT 

***Invoking entry point 

RSLT = DBSET (DSNAME, BEGIN) 
IF (RSLT) CALL EXCEPT 
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Explicitly Freeing Records 

When your program locks a record, DMSn guarantees you exclusive use of that record 
until your program frees (unlocks) the record. Freeing a record releases the record from 
all lock or secure restrictions so that the record is available to other users and programs. 

Depending on which DASDL options are set for the database and whether or not 
the program is in transaction state, several data management operations implicitly 
firee a record by repositioning the current path. However, if your program is outside 
of transaction state, you can explicitly free a record by executing a free operation. If 
there is no concurrency control for the database, you can e:qplicitly free a record within 
transaction state by executing a free operation. 

Note: If a record is part of a locked or secured structure, you cannot 

explicitly free the record. The entire structure must he explicitly freed 
in order for the record to he freed. 

For more details on explicitly and implicitly freeimg records, read the DMSII Application 
Programming Guide. For more information on explicitly freeing a structure, read 
"Esplicitly Freeing Structures" later in this section. 

Passing a Parameter 

The standard entry point used to explicitly free a record has one required 
parameter— the structure where the record is stored. 

Parameter Explanation 

<structure> Identifies either a data set (to free a data set record) or a database (to 

free a global data record). 

Note that DMSII frees the current record in the named structure. Therefore, if the 
structure is a data set, DMSII frees the current data set record. If the structure is a 
database, DMSII frees the global data record. 

Table 3-5 gives the exported names of the entiy points, along with the parameter and 
tibe data type of the parameter. 



Table 3-5. Explicitly Freeing Records 







Data Type of 


Exported Name off Entry Point 


Parameter 


Parameter 


ALGOLFREE 


<structure> 


STRING 


DBFREE 


<structure> 


DISPLAY 


FORTRAN77FREE 


<structure> 


CHARACTER 



You can explicitly free either a data set record or a global data record. The name of the 
structure must be unique. The following syntax diagram shows you can use a maximum 
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Explicitly Freeing Records (cont.) 



of 12 qualifying parameters to uniquely identify the data set name. The database name 
cannot be qualified. 



<structure> 



-J— <data set qualified name>- 
'--<database name> 



<data set qualified name> 





H /12\ 1 


- "■ 1 




— 1— OF — <name>— '— 






/12\ , 






L— L- . — <name>-' — ' 





The variable elements of the structure parameter are explained as follows: 
Element Explanation 

<clata set Identifies tiie data set tiiat is accessed at run time. Tiiis element is used 

qualified name> only to free a data set record. 

<datalDase Identifies tiie datatrase for which the DIVIINTERPRETER library was 

name> compiled. Thiis element is used only to free a global data record. 

<name> Identifies either the data set or the database. A name can consist of from 

1 to 17 letters, digits, and— depending on the language— either 
underscores (_) or hyphens (-). The first character must be a letter. The 
last character must be either a letter or a digit. 

For example, if your program accesses two databases (DBl and DB2) and each database 
has a data set named CLASS, you must qualify the data set name by naming the 
database. 



Programming Examples 

The following program fr£^ments show how to imlock a record in the data set EMB 
Because the data set name EMP is unique, you need not qualify it. 
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Explicitly Freeing Records (cont.) 



ALGOL Program Fragment 

%Declaring local variables 

STRING 

DATA_SET__NAME; 
BOOLEAN 

RSLT; 

%Ass1gnin9 values to parameters 
DATA_SET_NAME : =" EMP" ; 
%Declaring library entry point 
LIBRARY DMI; 

BOOLEAN PROCEDURE DBFREE (STRUCTURE) ; 
STRING STRUCTURE; 

LIBRARY DMI (ACTUALNAME="ALGOLFREE") ; 

%Invoking entry point 

RSLT:=DBFREE(DATA_SET_NAME) ; 
IF RSLT 

THEN EXCEPTIONHANDLER; 



C0B0L74 or C0B0L85 Program Fragment 

Note: In the following example, the variable RESULT is declared as 
a COMP item, making this example a COBOL74 or COBOL85 
program fragment. If RESULT is declared as a COMP item, this 
fragment could be used in a COBOL program. 

***Decl ari ng vari abl es 

01 DATA-SET-NAME PIC X(17) VALUE IS "EMP". 

01 RESULT PIC 9(1) COMP VALUE IS 0. 

★★★Invoking entry point 

CALL "DBFREE OF DMINTERPRETER" 
USING DATA-SET-NAME 
GIVING RESULT. 
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Explicitly Freeing Records (cont.) 



FORTRAN?? Program Fragment 

***Declanng library entry point 

LOGICAL FUNCTION DBFREE (STR) 
CHARACTER STR 

IN LIBRARY DMI (ACTUALNAME = "FORTRAN? 7 FREE") 

END 

***Setting variables to initial values 

CHARACTER DSNAME *4 /"EMP"/ 

***Declanng local variables 

LOGICAL RSLT 

***Invol(ing entry point 

RSLT = DBFREE (DSNAME) 
IF (RSLT) CALL EXCEPT 
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Explicitly Freeing Structures 

When your program locks a structure, DMSn guarantees you exclusive use of that 
structure and all its records until your program frees (unlocks) the structure. Freeing a 
structure releases the structure from all lock or secure restrictions so that the structure 
is available to other users and programs. All locked or secured records in the structure 
are freed. 

You must explicitly free a structure. You cannot implicitly free a structure. 

Note: If a record is part of a locked or secured strujcture, you cannot 

explicitly free the record. The entire structure must be explicitly freed 
in order for the record to be freed. 



Passing a Parameter 

The standard entry point used to explicitly free a record has one required 
parameter —the name of the data set in which the structure is stored. 

Parameter Explanation 

<data set Identifies the data set that is accessed at run time, 

qualified name> 

Table 3-6 gives the exported names of the entry points, along with the parameter and 
the data type of the parameter. 



Table 3-6. Explicitly Freeing Structures 







Data Type of 


Exported Name of Entry Point 


Parameter 


Parameter 


ALGOLFREESTR 


<data set qualified name> 


STRING 


DBFREE 


<data set qualified name> 


DISPLAY 


FORTRAN77FREE 


<data set qualified name> 


CHARACTER 



The name must be unique. You can use a twa-ginniini of 12 qualifying parameters to 
uniquely identify the data set name. 



<data set qualified name> 

— <naine> 



— /12\ 
OF — <naine: 

T* /12\ 

•— <naine: 
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Explicitly Freeing Structures (cont.) 



The variable elements of the data set parameter are explained as follows: 
Element Explanation 

<clata set Identifies the data set that is accessed at run time. This element is used 

qualified name> only to free a data set record. 

<name> Identifies the data set. A name can consist of from 1 to 17 letters, digits, 

and— depending on the language— either underscores (_) or hyphens (-). 
The first character must be a letter. The last character must be either a 
letter or a digit. 

Programming Examples 

The following program fragments show how to free a structm-e in the data set EME 
Because the data set name EMP is imique, you need not qualii^ it. 



ALGOL Program Fragment 

%Declanng local variables 

STRING 

DATA^SETJAME; 
BOOLEAN 

RSLT; 

%Ass1gn1ng values to parameters 
DATA_SET_NAME:="EMP"; 
%Declaring library entry point 
LIBRARY DMI; 

BOOLEAN PROCEDURE DBFREESTR(STRUCTURE) ; 
STRING STRUCTURE; 

LIBRARY DMI (ACTUALNAME="ALGOLFREESTR") ; 

%Invoking entry point 

RSLT:=DBFREESTR(DATA_SET__NAME) ; 
IF RSLT 

THEN EXCEPTIONHANDLER; 



3-22 



8600 0155-000 



Explicitly Freeing Structures (cont.) 



C0B0L74 or C0B0L85 Program Fragment 

Note: In the following example, the variable RESULT is declared as 
a COMP item, making this example a COBOL74 or COBOL85 
program fragment. If RESULT is declared as a COMP item, this 
fragment could be used in a COBOL program. 

***Declanng variables 

01 DATA-SET-NAME PIC X(17) VALUE IS "EMP". 

01 RESULT PIC 9(1) COMP VALUE IS 0. 

***Invoking entry point 

CALL "DBFREESTR OF DMINTERPRETER" 
USING DATA-SET-NAME 
GIVING RESULT. 



F0RTRAN77 Program Fragment 

***Declaring library entry point 

LOGICAL FUNCTION DBFSTR (STR) 
CHARACTER STR 

IN LIBRARY DMI (ACTUALNAME = "FORTRAN77FREESTR") 

END 

***Setting variables to initial values 

CHARACTER DSNAME *4 /"EMP"/ 

***Declaring local variables 

LOGICAL RSLT 

***Invoking entry point 

RSLT = DBFSTR (DSNAME) 
IF (RSLT) CALL EXCEPT 
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Finding Records 

The find operation retrieves a data record from the database, using a serial search, 
a random search, or a combined search. A serial search retrieves records using the 
phj^ical sequence of records. A random search retrieves records based on selection 
criteria. You also can search for a record using both the physical location and selection 
criteria. For example, you can retrieve the next record in a data set where the last name 
is the same £is the current record. 

The find operation does not lock or secure the record. 

Note: This entry point corresponds to the language extension FIND 
statement However, the interpretive interface entry point is 
more sophisticated. Several restrictions have been eased, 
and some algorithmic enhancements have been made. These 
improvements— as well as a discussion of search and retrieval 
techniques, current records and paths, and user work areas— are 
detailed in the DMSn Application Programming Guide. 



Passing Parameters 

The standard entry point used to find a record has three parameters: the direction of 
the retrieval, the name of the structure, and any condition to be used in the search for 
the record. 

Parameter Explanation 

<direction> Identifies the physical sequence for a sequential search. 

<structure> identifies the structure to t}e searched. It can be either a data set, 

an index set, or a database. 

<condition> Identifies restrictions for a random search. 



Only the name of structure is required; the other parameters are optionaL If only the 
name is given, the current record is moved to the user work area. 

Tabte 3-7 gives the sported names of the entry points, along with the parameters and 
the data type of each parameter. 
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Table 3-7. Finding Records 



Exported Name of Entry Point 


Parameter 


Data Type of 
Parameter 


ALGOLFIND 


<ciirection> 


STRING 




<structure> 


STRING 




<condition> 


STRING 


DBFIND 


<direction> 


DISPLAY 




<structure> 


DISPLAY 




<condition> 


DISPLAY 


F0RTRAN77FIND 


<direction> 


CHARACTER 




<structure> 


CHARACTER 




<condition> 


CHARACTER 



Direction 

The direction parameter is part of the serial search. Use the following syntax to identify 
the direction of a sequential search: 



<direction> 





- FIRST - 


-■ 1 




- NEXT — 






- PRIOR - 






1- LAST -J 





The variable elements of the direction parameter are explained as follows: 
Bement Explanation 

empty or blanks (Delault) Indicates that the find operation does not use a sequential 
search. 

Note: If you leave both the direction and condition 

parameters blank, DMSII transfers the current record 
in the sp&dfied structure to the user work area. 

FIRST Transfers the first record in the specified structure to the user work area. 

NEXT Transfers the next record in the specified stmcture to the user work area. 

PRIOR Transfers the prior record in the specified stmcture to the user work area. 

LAST Transfers the last record in the specified structure to the user work area. 
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structure 

The structure to be searched can be either a data set, an index set, or a database. The 
following syntax diagram shows if the name of the data set or index is not tmique, you 
can use a Tnaximnm of 12 qualifying parameters to uniquely identify the data set or index 
set. The database name cannot be qualified. 



< structure > 



— r-<data set qualified name>- 
[-<index set qualified nm&> 
l— <database nanie> 



<quaiified name> 

— <name>^ 



/12\ 



OF — <name 
— /12\ 
. — <r»ame> 



The variable elements of the structure parameter are explained as follows: 



Element 

<data set 
qualified name> 

< index set 
qualified name> 

<database 
name> 

<name> 



Explanation 

Identifies the data set to be searched at run time. 

Identifies the Index set to be searched at run time. 

identifies the database for which the DMINTERPRETER library was 
compiled. \^ 

Identifies either a data set, an index set, or a database. A name can 
consist of from 1 to 17 letters, digits, and —depending on the 
language -either underscores (_) or hyphens (-). The first character 
must be a letter. The last character must be either a letter or a digit. 

For example, if your program accesses two databases (DBl and DB2) and each database 
has a data set named CLASS, you must qualify the data set name naming the 
database. 

Conditions 

Use the following syntax to identify any conditions governing a random search: 



<condttion> 



selection expression^ 
1 1 nk> 
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The variable elements of the condition parameter are explained as follows: 
Element Explanation 

empty or blanks (Default) Indicates that the search does not use any selection criteria. 

Note: If you leave both the condition and direction 

parameters blank, DMSII transfers the current record 
in the specified structure to the user work area. 

<selection Establishes criteria for the search during the find operation. (For 

expression > languages that also support language extensions, consult the reference 

manual for selection ^pression syntax. Read the DMSII Application 
Programming Guide for a detailed explanation of a selection 
expression.) 

<iink> Identifies the database structure or data set item that links the current 

record to a record in another data set. 



Programming Examples 

In the following program fragments, the program retrieves the tirst record in which 
EMP-NO is equal to 11 in the data set EME 

ALGOL Program Fragment 

%Decl ari ng 1 ocal van abl es 

STRING 

FIRST_1, 

DATA_SET_NAME, 

CONDITION J; 
BOOLEAN 

RSLT 

%Ass1gn1ng values to parameters 

FIRST_1:="FIRST"; 
DATA_SET_NAME : =" EMP" ; 
C0NDITI0N__1 : EMP-N0=11» ; 

%Dec1ar1ng library entry point 

LIBRARY DMI; 

BOOLEAN PROCEDURE DBFIND (DIRECTION. STRUCTURE.CONDITION) ; 
STRING DIRECTION, STRUCTURE, CONDITION; 
LIBRARY DMI (ACTUALNAME="ALGOLFIND") ; 

%Invoking entry point 

RS LT : =DBFIND ( FI RST_1 , DATA_SET_NAME, C0NDITI0N_1) ; 
IF RSLT 

THEN EXCEPTIONHANDLER; 
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C0B0L74 or C0B0L85 Program Fragment 

Note: In this example, the variable RESULT is declared as a COMP item, 
making this example a COBOL74 or C0B0L85 program fragment. 
If RESULT were declared as a COMP-2 item, this fragment could be 
used in a COBOL program. 

***Declaring variables 

01 FIRST-1 PIC X(5) VALUE IS "FIRST". 

01 DATA-SET-NAME PIC X(17) VALUE IS "EMP". 

01 CONDITION-1 PIC X(9) VALUE IS "EMP-N0=11". 

01 RESULT PIC 9(1) COMP VALUE IS 0. 

★★★Invoking entry point 

CALL "DBFIND OF DMINTERPRETER" 

USING FIRST-1, DATA-SET-NAME, CONDITION-1 
GIVING RESULT. 



FORTRAN?? Program Fragment 

***Declaring library entry point 

LOGICAL FUNCTION DBFIND (STR, ITEM, WHERE) 
CHARACTER STR, ITEM, WHERE 

IN LIBRARY DMI (ACTUALNAME = "F0RTRAN77FIND") 

END 

***Setting variables to initial values 

CHARACTER FIRST *10 /"FIRST"/ 

* DSNAME *4 /"EMP"/ 

* COND *9 /"EMP-N0=11"/ 

***Decl ari ng 1 ocal vari abl es 

LOGICAL RSLT 

***Invol<ing entry point 

RSLT = DBFIND(FIRST,DSNAME,COND) 
IF (RSLT) CALL EXCEPT 
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Locking Records 



The lock operation has two main objectives: to find a designated record and to lock the 
record. Locking the record prevents other users from simiiltaneously modifying the 
record. A program might lock a record (and check the content) before deleting the 
record or changing the values in a field. 

Note: This entry point functions in the same manner as does the find 

operation entry point except that a record is locked after it is found. 
The entry point can locate a record using a random, sequential, or 
combination search. Refer to "Finding Records" in this section. 



Passing Parameters 

The standard entry point used to find and lock a record has three parameters: the 
direction of the retrieval, the name of the structure, and any condition to be used in the 
search for the record. 



Parameter 

<dlrection> 
<structure> 

<conclition> 



Explanation 

Identifies the physical sequence for a sequential search. 

Identifies the structure to be searched. It can be either a data set, 
an index set, or a database. 

Identifies restrictions for a random search. 



Only the name of structure is required; the other parameters are optional. If only the 
name is given, the current record is moved to the user work area and locked. 

Table 3-8 gives the exported names of the entry points, along with the parameters and 
the data t3^e of each parameter. 

Table 3-8. Locking Records 



Exported Name of Entry Point 


Parameter 


Data Type of 
Parameter 


ALGOLLOCK 


<direction> 


STRING 




<structure> 


STRING 




<condition> 


STRING 


DBLOCK 


<direction> 


DISPLAY 




<structure> 


DISPLAY 




<condition> 


DISPLAY 


FORTRAN77LOCK 


<directlon> 


CHARACTER 




<structure> 


CHARACTER 




<condition> 


CHARACTER 
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Direction 

The direction parameter is part of the serial seardhu Use the following syntax to identify 
the direction of a sequential search: 

<direction> 





- FIRST - 


■ 1 




- NEXT — 






- PRIOR - 






L- LAST -J 





The variable elements of the direction parameter are explained as follows: 



Element 

empty or blanks 



FIRST 
NEXT 
PRIOR 
LAST 



Explanation 

(Default) Indicates that the lock operation does not use a sequential 
search. 

Note: If you leave both the direction and condition 

parameters blank, DMSII transfers the current record 
in the specified structure to the user work area. 

Transfers the first record in the specified structure to the user work area 
and locks it. 

Transfers the next record in the specified structure to the user work area 
and locks it. 

Transfers the prior record in the specified structure to the user work area 
and locks it. 

Transfers the last record in the specified stmcture to the user work area 
and locks it. 



Structure 

The structure to be searched can be either a data set, an index set, or a database. The 
following syntax diagram shows if the name of the data set or index set is not imique, 
you can use a tnaximum of 12 qualifying parameters to imiquely identify the data set or 
index set. The database name cannot be qualified. 



<structure> 



— r-<data set qualified naine>- 
h-<index set qualified name? 
>-<database naine> 



< qualified name> 





H /12\ , 


1 




— 1- OF — <name>— *— 






f /12\ 1 






L_I_ . — <name>— > — ' 
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The variable elements of the structure parameter are explained as follows: 



Element 

<data set 
qualified name> 

< index set 
qualified name> 

<database 
name> 

<name> 



Explanation 

Identifies the data set that is searched at run time. 
Identifies the index set that is searched at run time. 



Identifies the database for which the DMiNTERPRETER library was 
compiled. 

Identifies either a data set, an index set, or a database. A name can 
consist of from 1 to 17 letters, digits, and— depending on the 
language— either underscores {_) or hyphens (-). The first character 
must be a letter. The last character must be either a letter or a digit. 



For example, if your program accesses two databases (DBl and DB2) and each database 
has a data set named CLASS, you must qualify the data set name by naming the 
databzise. 



Conditions 

Use the following syntax to identify any conditions governing a random search: 



<condition> 



—<:sel action express! on>— 
I_<1 ink> ■ ' 

The variable elements of the condition parameter are e^lained as follows: 
Element Explanation 

empty or blanks (Default) Indicates that the search does not use any selection criteria. 



Note: If you leave both the direction and condition 

parameters blank, DMSH transfers the ciarent record 
in the specified structure to tiie user work area. 

<selection Establishes criteria for the search during the lock operation. (For 

expression > languages that also support language extensions, consult the reference 

manual for selection expression syntax. Read the DMSH Application 
Programming Guide for a detailed explanation of a selection 
expression.) 

< link> Identifies the database stmcture or data set item that links the cunrent 

record to a record in another data set. 
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Programming Examples 

In the following program fragments, the program retrieves the first record in which 
EMP-NO is equal to 11 in the data set EME The record is then locked. 

ALGOL Program Fragment 

%Declan"ng local variables 

STRING 

FIRST_1, 

DATAJET_NAME, 

CONDITION 1; 
BOOLEAN 

RSLT 

%Assigning values to parameters 

FIRST_1:=" FIRST"; 
DATA_SET_NAME: =" EMP" ; 
C0NDITI0N_1 : =" EMP-N0=11 " ; 

%Declanng library entry point 

LIBRARY DMI; 

BOOLEAN PROCEDURE DBLOCK(DIRECTION,STRUCTURE, CONDITION) ; 
STRING DIRECTION, STRUCTURE, CONDITION; 
LIBRARY DMI (ACTUALNAME="ALGOLLOCK") ; 

%Involcing entry point 

RSLT:=DBL0CK(FIRST_1,DATA_SET_NAME,C0NDITI0N_1) ; 
IF RSLT 

THEN EXCEPTIONHANDLER; 
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C0B0L74 or COBOL85 Pr(^am Fragment 

Notes In the following example, the variable RESULT is declared as 
a COMP item, making this example a COBOL74 or COBOL85 
program fragment. If RESULT were declared as a COMP-2 item, 
this fragment could be used in a COBOL program. 

***Decl an" ng van' abl es 

01 FIRST-1 PIC X(5) VALUE IS "FIRST". 

01 DATA-SET-NAME PIC X(17) VALUE IS "EMP". 

01 CONDITION-1 PIC X(9) VALUE IS "EMP-N0=11". 

01 RESULT PIC 9(1) COMP VALUE IS 0. 

***Invoking entry point 

CALL "DBLOCK OF DMINTERPRETER" 

USING FIRST-1, DATA-SET-NAME, CONDITION-1 
GIVING RESULT. 



FORTRAN?? Pr(^am Fragment 

***Dec1anng library entry point 

LOGICAL FUNCTION DBLOCK (STR, ITEM, WHERE) 
CHARACTER STR, ITEM, WHERE 

IN LIBRARY DMI (ACTUALNAME = "FORTRAN77LOCK") 

END 

***Setting variables to initial values 

CHARACTER FIRST *10 /"FIRST"/ 

* DSNAME *4 /"EMP"/ 

* COND *9 /"EMP-N0=11"/ 

***Dec1aring local variables 

LOGICAL RSLT 

***Invoking entry point 

RSLT = DBLOCK(FIRST,DSNAME,COND) 
IF (RSLT) CALL EXCEPT 
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Locking Structures 



The lock structure operation has two main objectives: to find the designated structure 
and to lock the structure. Locking a structure prevents other users from simultaneotisly 
modifying the structure. 

All records in the structure are locked. The records are freed only when the structure is 
e^Iicitly freed or the database is closed. The records are not implicitly freed after the 
DMSn executes an end transaction operation. 

Read "Freeing Structures'* in this section for more information on explicitly freeing 
a structure. Head "Closing a Database" in this section for more details on closing a 
database. 

Passing a Parameter 

The standard entry point used to find and lock a structiu'e has one parameter— the name 
of the data set that is accessed at run time. 



Parameter 

<data set quaiified 
name> 



Explanation 

Identifies the data set to be accessed at run time. 



Table 3-9 gives the exported names of the entry points, along with the parameters and 
the data type of each parameter. 



Table 3-9. Locking Structures 







Data Type of 


Exported Name of Entry Point 


Parameter 


Parameter 


ALGOLLOCKSTR 


<data set qualified name> 


STRING 


DBLOCKSTR 


<data set quaiified name> 


DISPLAY 


FORTRAN77LOCKSTR 


<data set qualified name> 


CHARACTER 



The data set must be uniquely identified. You can use a maximum of 12 qualifyii^ 
parameters to uniquely id^tify the data set. 



<data set qualified name> 

— <name>- 



/12\ 



OF — <name> 
— /12\ - 
. — <naine 
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The variable elements of the data set parameter are esqplained as foUovtrs: 



Element 



Explanation 



<data set 
qualified name> 



Identifies the data set that is searched at run time. 



<name> 



Identifies the data set. A name can consist of from 1 to 17 letters, digits, 
and— depending on the language— either underscores (_) or hyphens (-}. 
The first character must be a letter. The last character must be either a 
letter or a digit. 



Programming Examples 

In the following program fragments, the program retrieves and locks the data set 
DATA_SET_NAME. All records in the data set are locked. The entire structure must be 
explicitly freed in order to free any of the locked records. 

ALGOL Pr<^am Fragment 

%Declanng local variables 

STRING 

DATA_SET_NAME, 
BOOLEAN 

RSLT 

%Assigning values to parameters 
DATA_SET_NAME:="EMP"; 
%Declanng library entry point 
LIBRARY DMI; 

BOOLEAN PROCEDURE DBLOCKSTR (STRUCTURE) ; 
STRING STRUCTURE 

LIBRARY DMI (ACTUALNAME="AL60LL0CKSTR") ; 

%Invol(ing entry point 

RSLT:=DBLOCKSTR(DATA_SET_NAME) ; 
IF RSLT 

THEN EXCEPTIONHANDLER; 
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C0B0L74 or C0B0L85 Program Fragment 

Note: In the following example, the variable RESULT is declared as 
a COMP item, making this example a COBOL74 or COBOL85 
program fragment If RESULT were declared as a COMP-2 item, 
this fragment could be used in a COBOL program. 



***Invoking entry point 

CALL "DBLOCKSTR OF DMINTERPRETER" 
USING DATA-SET-NAME 
GIVING RESULT. 



F0RTRAN77 Program Fragment 

***Declaring library entry point 

LOGICAL FUNCTION DBSTR (ITEM) 
CHARACTER ITEM 

IN LIBRARY DMI (ACTUALNAME = "FORTRAN77LOCKSTR") 

END 

***Setting variables to initial values 

CHARACTER DSNAME *4 /"EMP"/ 

***Declaring local variables 

LOGICAL RSLT 

***Invoking entry point 

RSLT = DBSTR(DSNAME) 
IF (RSLT) CALL EXCEPT 



***Declaring variables 



01 DATA-SET-NAME 
01 RESULT 



PIC X (17) VALUE IS "EMP". 
PIC 9(1) COMP VALUE IS 0. 
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Securing Records 



The seciu'e operation has two main objectives: to find a designated record and to secure 
the record. Securing a record guarantees no other user can modify the record but allows 
other users to access the record and retrieve information. 

Note: This entry point functions in the same mcainer as does the find 

operation entry point except that a record is secured after it is found. 
The entry point can locate a record using a random, sequential, or 
combination search. Refer to "Finding Records" in this section. 



Passing Parameters 

The standard entry point used to find and secure a record has three parameters: the 
direction of the retrieval, the name of the structure, and any condition to be used in the 
search for the record. 



Parameter 

<direction> 
<structure> 

<condltion> 



Explanation 

Identifies the physical sequence for a sequential search. 

Identifies the structure to be searched. It can be either a data set, 
an ind®( set, or a database. 

Identifies restrictions for a random search. 



Only the name of structure is required; the other parameters are optional. If only the 
name is given, the current record is moved to the user work area and secured. 

Table 3-10 gives the exported names of the entry points, aloi^ with the parameters and 
the data type of each parameter. 



Table 3-10. Securing Records 



Exported Name of Entry Point 


Parameter 


Data Type of 
Parameter 


ALGOi.SECURE 


<directlon> 


STRING 




<structure> 


STRING 




<condition> 


STRING 


DBSECURE 


<direction> 


DISPLAY 




<structure> 


DISPLAY 




<condltion> 


DISPLAY 


F0RTRAN77SECURE 


<direction> 


CHARACTER 




<structure> 


CHARACTER 




<condition> 


CHARACTER 
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Direction 

The direction parameter is part of the serial search. Use the foUovong i^tax to identify 
the direction of a sequential search: 



<cnrection> 





- FIRST - 


■ ■ 1 




- NEXT — 






- PRIOR - 






L. LAST — 1 





The variable elements of the direction parameter are explained as follows: 
Element Explanation 

empty or blanks (Default) Indicates that the secure operation does not use a sequential 
search. 

Note: If you leave both the direction and condition 

parameters blank, DMSII transfers the current record 
in the specified structure to the user work area. 

FIRST Transfers the first record in the specified structure to the user work area 

and secures it. 

NEXT Transfers the next record in the specified structure to the user work area 

and secures it. 

PRIOR Transfers the prior record in the specified structure to the user work area 

and secures it. 

LAST Transfers the last record in the specified structure to the user work area 

and secures it. 

Structure 

The structure to be searched can be either a data set, an index set, or a database. The 
following S5nitax diagram shows if the name of the data set or index set is not xmique, 
you can use a maximnm of 12 qualifying parameters to xmiquely identify the data set or 
index set. The database name cannot be qualified. 

<$tructure> 

— [— <data set qualified naine> — i 1 

k^index set qualified name>— 
'--<database naine> ' 



<qualffied name> 

— <naine>- 



/12\ 



OF — <name: 
— /12\ 
. — <naine> 
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Securing Records (cont.) 



The variable elements of the structure parameter are explained as follows: 



Element 

<clata set 
qualified name> 

< index set 
qualified name> 

<database 
name> 

<name> 



Explanation 

Identifies the data set that is searched at run time. 
Identifies the index set that is searched at run time. 



Identifies the database for which the DMINTERPRETER library was 
compiled. 

Identifies either a data set, an index set, or a database. A name can 
consist of from 1 to 17 letters, digits, and— depending on the 
language— either underscores (_) or hyphens (-). The first character 
must be a letter. The last character must be either a letter or a digit. 

For example, if your program accesses two databases (DBl and DB2) and each database 
has a data set named CLASS, you must qualify the data set name by naming the 
database. 



Conditions 

Use the following syntax to identify any conditions governing a random search: 



<condition> 



b 



sel ecti on expressi on: 
1 1 n k> 



The variable elements of the condition parameter are explained as follows: 
Element Explanation 

empty or blanks (Default) Indicates that the search does not use any selection criteria. 

Note: If you leave both the direction and condition 

parameters blank, DMSII transfers the current record 
in the specified structure to the user work area. 



<selection 
expression > 



<link> 



Establishes criteria for the search during the secure operation. (For 
languages that also support language extensions, consult the reference 
manual for selection expression syntax. Read the DMSII Application 
Programming Guide for a detailed explanation of a selection 
expression.) 

Identifies the datat)ase structure or data set Item that links the current 
record to a record in another data set. 
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Programming Examples 

In the following program fragments, the program retrieves the first record in which 
EMP-NO is equal to 11 in the data set EME The record is then secured. 

ALGOL Program Fragment 

%Declanng local variables 

STRING 

FIRST_1, 

DATA_SET_NAME, 

CONDITION 1; 
BOOLEAN 

RSLT 

%Assigning values to parameters 

FIRST_1:="FIRST"; 
DATA_SET_NAME : = " EMP" ; 
CONDITION^l : =" EMP-NO=H " ; 

%Declaring library entry point 

LIBRARY DMI; 

BOOLEAN PROCEDURE DBSECURE (DIRECTION, STRUCTURE.CONDITION) ; 
STRING DIRECTION, STRUCTURE, CONDITION; 
LIBRARY DMI (ACTUALNAME="ALGOLSECURE") ; 

%Invoking entry point 

RS LT : =DBSECURE (FI RST_1 , DATA_SET_NAME ,C0NDITI0N_1) ; 
IF RSLT 

THEN EXCEPTIONHANDLER; 
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Securing Records (cont.) 



C0B0L74 or C0B0L85 Program Fragment 

Note: In the following example, the variable RESULT is declared as 
a COMP item, making this example a COBOL74 or COBOL85 
program fragment. If RESULT were declared as a COMP-2 item, 
this fragment could be used in a COBOL program. 

***Decl an ng vari abl es 

01 FIRST-1 PIC X{5) VALUE IS "FIRST". 

01 DATA-SET-NAME PIC X(17) VALUE IS "EMP". 

01 CONDITION-1 PIC X(9) VALUE IS "EMP-N0=11". 

01 RESULT PIC 9(1) COMP VALUE IS 0. 

***Invoking entry point 

CALL "DBSECURE OF DMINTERPRETER" 

USING FIRST-1, DATA-SET-NAME, CONDITION-1 
GIVING RESULT. 



FORTRAN?? Program Fragment 

***Declaring library entry point 

LOGICAL FUNCTION DBSEC (STR,ITEM,WHERE) 
CHARACTER STR, ITEM, WHERE 

IN LIBRARY DMI (ACTUALNAME = "FORTRAN77SECURE") 

END 

***Setting variables to initial values 

CHARACTER FIRST *10 /"FIRST"/ 

* DSNAME *4 /"EMP"/ 

* COND *9 /"EMP-N0=11"/ 

***Declaring local variables 

LOGICAL RSLT 

***Invoking entry point 

RSLT » DBSEC(FIRST,DSNAME,COND) 
IF (RSLT) CALL EXCEPT 
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Securing Structures 

The secure structure operation has two main objectives: to find the designated 
structure and to secure the structure. Securing a structure prevents other users from 
simultaneously modifying any records in the structure. However, other users can access 
and retrieve information from records in the structure. 

An records in the structure are secured. The records are freed only when the structure 
is explicitly freed or the database is closed. The records are not implicitly freed after the 
DMSn executes an end transaction operation. 

Kead "Freeing Structures" in this section for more information on explicitly freeing 
a structure. Read "Closing a Database" in this section for more details on closing a 
database. 



Passing a Parameter 

The standard entry point used to find and secure a structure has one parameter— the 
name of the data set that is accessed at run time. 

Parameter Explanation 

<data set qualified identifies the data set to be accessed at run time. 

name> 

Table 3-11 gives the e:sported names of the entry points, along with the parameters and 
the data type of each parameter. 



Table 3-1 1 . Securing Structures 







Data Type of 


Exported Name of Entry Point 


Parameter 


i^rameter 


ALGOLSECURESTR 


<data set qualified name> 


STRING 


DBSECURESTR 


<data set qualified name> 


DISPLAY 


F0RTRAN77SECURESTR 


<data set qualified name> 


CHARACTER 



The data set must be imiquely identified. You can use a maximum of 12 qualifying 
parameters to imiquely identify the data set. 



<data set qualified name> 

— <name>- 



/12\ - 

OF — <naroe:' 
— /12\ — 
. — <name>- 
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The variable elements of the data set parameter are explained as follows: 
Element Explanation 

<data set Identifies tlie data set that is searched at run time, 

qualified name> 

<name> Identifies the data set. A name can consist of from 1 to 17 letters, digits, 

and— depending on the language— either underscores (_) or hyphens (-). 
The first character must be a letter. The last character must be either a 
letter or a digit. 

Programming Examples 

In the following program fragments, the program retrieves and secures the data set 
DATA_SET_NAME. All records in the data set are secured: other users can access 
information but cannot modify information. 



ALGOL Program Fragment 

%Declaring local variables 

STRING 

DATA_SET_NAME. 
BOOLEAN 

RSLT 

%Assigning values to parameters 

DATA_SET_NAME: EMP" ; 

%Declanng library entry point 

LIBRARY DMI; ' 
BOOLEAN PROCEDURE DBSECURESTR (STRUCTURE) ; 
STRING STRUCTURE 

LIBRARY DMI ( ACTUALNAME=" ALGOLS ECU RESTR" ) ; 

%Invoking entry point 

RSLT:=DBSECURESTR(DATA_SETJAME); 
IF RSLT 

THEN EXCEPTIONHANDLER; 
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C0B0L74 or C0B0L85 Program Fragment 

Note: In the following example, the variable RESULT is declared as 
a COMP item, making this example a COBOL74 or C0B0L85 
program fragment. If RESULT were declared as a COMP-2 item,, 
this fragment could be used in a COBOL program. 

***Declaring variables 

01 DATA-SET-NAME PIC X(17) VALUE IS "EMP". 

01 RESULT PIC 9(1) COMP VALUE IS 0. 

***Invoking entry point 

CALL "DBSECURESTR OF DMINTERPRETER" 
USING DATA-SET-NAME 
GIVING RESULT. 



FORTRAN?? Program Fragment 

***Declaring library entry point 

LOGICAL FUNCTION DBSSTR (ITEM) 
CHARACTER ITEM 

IN LIBRARY DMI (ACTUALNAME = "F0RTRAN77SECURESTR") 

END 

***Setting variables to initial values 

CHARACTER DSNAME *4 /"EMP"/ 

***Declaring local variables 

LOGICAL RSLT 

***Invol<ing entry point 

RSLT = DBSSTR (DSNAME) 
IF (RSLT) CALL EXCEPT 
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Begin Transaction — Entering Transaction State 

For each audited database, DMSII maintains a log (audit trail) of all activities that 
update the database. For example, the audit trail notes aU records that are deleted or 
added and all data changes. This audit trail is used by the recovery software to prevent 
database corruption. 

When a program opens an audited database to update it, the database can be in one of 
two states: protected or transaction. In a protected state, no update activity can be 
performed. By default, an audited database is opened in a protected state. 

An application program must specifically place the audited database in the transaction 
state in order to perform any update activities, such as storing or deleting records. 

Notes: 

• DMSII ignores invocations to begin or end transaction state for 
unaudited databases. 

• Read the DMSII Application Programming Guide for transaction 
and recovery guidelines. 

Passing a Parameter 

The standard entry point used to place an opened, audited database in transaction state 
has one required parameter — the audit parameter. 

Parameter Explanation 

<aucljt> Specifies wiietiier an image of the current restart data set record is to be 

audited. (The restart data set is used for restart routines. Consult the 
DMSII DASDL Reference Manual for details about the content of 
the restart data set. Consult the DMSII Application Programming 
Guide for prc^ramming considerations.) 

Table 3-12 gives the exported names of the entry points, along with the parameter and 
the data type of the parameter. 



Table 3-12. Begin Transaction - Entering Transaction State 







Data Type of 


Exported Name of Entry Point 


Parameter 


Parameter 


ALGOLBEGINTRANSACTION 


<audit> 


STRING 


DBBEGINTRANSACTION 


<audlt> 


DISPLAY 


F0RTRAN77BEGINTRANSACTI0N 


<audit> 


CHARACTER 
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Entering Transaction State (cont.) 



Use the following syntax to begin transaction state: 
<audit> 

— ,- AUDIT \ 1 

L NOAUDIT -I 

Note: In order for your program to enter transaction state, you must set the 
value of the audit parameter to AUDIT. 

The variable element of the audit parameter is explained as follows: 
Element Explanation 

AUDIT DMSII audits an image of the current restart data set record. 

NOAUDIT DMSII does not perform an audit. 



Programming Examples 

The following program fragments place an opened, audited database in transaction state. 
DMSn audits an image of the current restart data set record. 

ALGOL Program Fragment 

%Declaring local variables 

STRING 

P_AUDIT; 
BOOLEAN 

RSLT; 

^Assigning values to parameters 
P_AUDIT:=" AUDIT"; 
%Declaring library entry point 
LIBRARY DMI; 

BOOLEAN PROCEDURE DBBEGINTRANSACTION (AUDIT) ; 
STRING AUDIT; 

LIBRARY DMI (ACTUALNAME="ALGOLBEGINTRANSACTION") 

%In voicing entry point 

RSLT:=DBBEGINTRANSACTION(P_AUDIT) ; 
IF RSLT 

THEN EXCEPTIONHANDLER; 
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Entering Transaction State (cont.) 



C0B0L74 or C0B0L85 Program Fragment 

Note: In the following example, the variable RESULT is declared as 
a COMP item, making this example a COBOL74 or COBOL85 
program fragment. If RESULT were declared as a COMP-2 item, 
this fragment could be used in a COBOL program. 

***Declan*ng variables 

01 P-AUDIT PIC X(5) VALUE IS "AUDIT". 

01 RESULT PIC 9(1) COMP VALUE IS 0. 

***Invoking entry point 

CALL "DBBEGINTRANSACTION OF DMINTERPRETER" 
USING P-AUDIT 
GIVING RESULT. 



FORTRAN?? Program Fragment 

***Declaring library entry point 

LOGICAL FUNCTION DBBTR (AUDIT) 
CHARACTER AUDIT 

IN LIBRARY DMI (ACTUALNAME = "F0RTRAN77BEGINTRANSACTI0N") 
END 

***Setting variables to initial values 

CHARACTER AUDIT *10 /"AUDIT"/ 

***Declaring local variables 

LOGICAL RSLT 

***Invoking entry point 

RSLT = DBBTR (AUDIT) 
IF (RSLT) CALL EXCEPT 
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Aborting Transactions 

An abort transaction operation discards all updates made in a transaction and brings 
the database back to the point immediately before the begin transaction operation 
that initiated the update activity. The program and all concurrent programs continue 
running. AQ other transactions are processed. 

Notes: 

• If the DASDL INDEPENDENTTRANS option is not set for the 

database, any attempt to abort a transaction is ignored. 

• DMSII ignores invocations to abort transactions for unaudited 
databases. 

• For audited databases, the database must be in transaction state 
to perform an abort operation. 

• Read the DMSII Application Programming Guide for transaction 
and recovery guidelines. 

Passing Parameters 

The standard entry point used to abort a transaction has no parameters. Table 3-13 
gives the e:q)orted names of the entry points. 

Table 3-13. Export Names of Entry Points Used to Abort a Transaction 



Export Names 
ALGOLABORTTiRANSACTION 
DBABORTTRANSACTION 
F0RTRAN77AB0RTTRANSACTI0N 



Programming Examples 

The following program fragments abort a transaction. The audited database must be in 
transaction state. 
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Aborting Transactions (cont.) 



ALGOL Program Fragment 

%Declaring local variables 

BOOLEAN 

RSLT; 

%Declanng library entry point 
LIBRARY DMI; 

BOOLEAN PROCEDURE DBABORTTRANSACTION; 

LIBRARY DMI (ACTUALNAME="ALGOLBEGINTRANSACTION") 

%Invoking entry point 

RSLT : =DBABORTTRANSACTION ; 
IF RSLT 

THEN EXCEPT lONHANDLER; 



C0B0L74 or C0B0L85 Program Fragment 

Note: In the following example, the variable RESULT is declared as 
a COMP item, making this example a COBOL74 or COBOL85 
program fragment. If RESULT were declared as a COMP-2 item, 
this fragment could he used in a COBOL program. 

***Declaring variables 

01 RESULT PIC 9(1) COMP VALUE IS 0. 

***Invoking entry point 

CALL "DBABORTTRANSACTION OF DMINTERPRETER" 
GIVING RESULT. 



FORTRAN?? Program Fragment 

***Declaring library entry point 

LOGICAL FUNCTION DBATR 

IN LIBRARY DMI (ACTUALNAME = "F0RTRAN77AB0RTTRANSACTI0N") 
END 

***Declaring local variables 

LOGICAL RSLT 

***Involcing entry point 

RSLT = DBATR 

IF (RSLT) CALL EXCEPT 
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Saving Transaction Points 

A save transaction point operation writes a savepoint record to the audit trail. The 
savepoint applies only to the current transaction and does not afiect hold/load recovery. 
You can write more than one savepoint record to the audit trail within a transaction. 

No^s: 

• If the DASDL INDEPENDENTTRANS option is not set for the 
database, any attempt to create a savepoint is ignored. 

• DMSII ignores invocations to save transaction points for 
unaudited databases. 

• For audited databases, the database must be in transaction state 
to perform a save transaction point operation. 

• Read the DMSII Application Programming Guide for transaction 
and recovery guidelines. 

Passing a Parameter 

The standard entry point used to save a transaction point has one required 
parameter — a imique identifier for the savepoint. 

Parameter Explanation 

<savepoint> Specifies the unique number assigned to tlie savepoint. 

Table 3-14 gives the exported names of the entry points, along with the parameter and 
the data type of the parameter. 



Table 3-14. Saving Transaction Points 







Data Type of 


Exported Name of Entry Point 


Parameter 


Parameter 


ALGOLSAVETRPOINT 


<savepoint> 


INTEGER 


DBSAVETRPOINT 


<savepoint> 


DISPLAY 


FORTRAN77SAVETRPOINT 


<savepolnt> 


INTEGER 



Use the following syntax to create a savepoint record: 



<savepoiiit> 

— <integer> 
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The variable element of the savepoint parameter is explained as follows: 
Element Explanation 

< int^er> A user-assigned whole number that uniquely identifies the savepoint 

record. The number must be enclosed within parentheses. 

Programming Examples 

The following program fragments write a savepoint record to the audit trail The 
database must be in transaction state. 

ALGOL Program Fragment 

%Declaring local variables 

INTEGER 

SAVE_POINT; 
BOOLEAN 

RSLT; 

%Assigning values to parameters 
SAVE_P0INT:="872"; 
%Declaring library entry point 
LIBRARY DMI; 

BOOLEAN PROCEDURE DBSAVETRPOINT (SAVE_POINT) ; 
INTEGER SAVE_POINT; 

LIBRARY DMI (ACTUALNAME="ALGOLSAVETRPOINT") 

%Invoking entry point 

RSLT: =DBSAVETRPOINT (SAVE^POINT) ; 
IF RSLT 

THEN EXCEPTIONHANDLER; 
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C0B0L74 or C0B0L85 Program Fragment 

Note: In the following example, the varidble RESULT is declared as 
a COMP item, making this example a COBOL74 or COBOL85 
program fragment. IfBESULT were declared as a COMP-2 item, 
this fragment could be used in a COBOL program. 

***Declanng variables 

01 S-POINT PIC X(l) VALUE IS "1". 

01 RESULT PIC 9(1) COMP VALUE IS 0. 

***Invoking entry point 

CALL "DBSAVETRPOINT OF DMINTERPRETER" 
USING S-POINT 
GIVING RESULT. 



FORTRAN?? Program Fragment 

***Declaring library entry point 

LOGICAL FUNCTION DBSAVE (SPOINT) 
STRING SPOINT 

IN LIBRARY DMI (ACTUALNAME = " FORTRAN? 7SAVETRP0I NT") 
END 

***Setting variables to initial values 

INTEGER SPOINT *10 /"l"/ 

***Declar1ng local variables 

LOGICAL RSLT 

***Invoking entry point 

RSLT = DBSAVE (SPOINT) 
IF (RSLT) CALL EXCEPT 
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Canceling Transactions Back to Savepoints 

Cancel transaction point operations abort the current transaction back to a specified 
savepoint. The program and all concurrent programs continue running. All other 
transactions are processed. 

Notes: 

• If the DASDL INDEPENDENTTRANS option is not set for the 
database, any attempt to cancel a transaction is ignored. 

• DMSII ignores invocations to cancel transactions for unaudited 
databases. 

• For audited databases, the database must be in transaction state 
to perform a cancel transaction point operation. 

• Read the DMSII Application Programming Guide for transaction 
and recovery guidelines. 

Passing a Parameter 

The standard entry point used to csmcel a transaction point has one required 
parameter— a unique identifier for the savepoint. 

Parameter Explanation 

<savepoint> Specifies tlie unique numtser assigned to tlie savepoint. 

Table 3-15 ^ves the exported names of the entry points, along with the parameter and 
the data type of the parameter. 



Table 3-15. Canceling Transactions Back to Savepoints 







Data Type of 


Exported Name of Entry Point 


Parameter 


Parameter 


ALGOLCANCELTRPOINT 


<savepoint> 


INTEGER 


DBCANCELTRPOINT 


<savepoint> 


DISPU^Y 


FORTRAN77CANCELTRPOINT 


<savepoint> 


INTEGER 



Use the f oUowimg syntax to identify a savepoint record: 



<savepoint> 

— <integer> 1 
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Canceling Transactions Back to Savepoints (cont.) 



The variable element of the savepoint parameter is explained as follows: 



Element 



Explanation 



<integer> 



A user-assigned whole number that uniquely identifies the savepoint 
record. The number must be enclosed within parentheses. 



If no corresponding savepoint record is found or if the savepoint parameter is not 
entered, all updates performed during the current transaction start are aborted. 
The cancel transaction point operation is executed as if it were an abort transaction 
operation. 

Programming Examples 

The following program fragments write a savepoint record to the audit trail. The 
database must be in transaction state. 

ALGOL Program Fragment 

%Declanng local variables 

INTEGER 

CANCEL_POINT; 
BOOLEAN 

RSLT; 

%Assigning values to parameters 
CANCEL_P0INT:="872"; 
%Declaring library entry point 
LIBRARY DMI; 

BOOLEAN PROCEDURE DBCANCELTRPOINT (CANCEL^POINT) ; 
INTEGER CANCEL_POINT; 

LIBRARY DMI (ACTUALNAME="ALGOLCANCELTRPOINT") 

%Invoking entry point 

RSLT :=DBCANCELTRPOINT (CANCEL POINT); 
IF RSLT 

THEN EXCEPTIONHANDLER; 
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C0B0L74 or C0B0L85 Program Fragment 

Note: In the following example, the variable RESULT is declared as 
a COMP item, making this example a COBOL74 or COBOL85 
program fragment. If RESULT were declared as a COMP-2 item, 
this fragment could be used in a COBOL program. 

***Declaring variables 

01 C-POINT PIC X(l) VALUE IS "1". 

01 RESULT PIC 9(1) COMP VALUE IS 0. 

***Invoking entry point 

CALL "DBCANCELTRPOINT OF DMINTERPRETER" 
USING S-POINT 
GIVING RESULT. 



F0RTRAN77 Program Fragment 

***Declaring library entry point 

LOGICAL FUNCTION DBCNCL (CPOINT) 
STRING CPOINT 

IN LIBRARY DMI (ACTUALNAME = "FORTRAN77CANCELTRPOINT") 
END 

***Setting variables to initial values 

INTEGER CPOINT *10 /"V/ 

***Declaring local variables 

LOGICAL RSLT 

***Invoking entry point 

RSLT = DBCNCL(CPOINT) 
IF (RSLT) CALL EXCEPT 
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Deleting Data Records 

The deletion operation has three main objectives: to find a designated record, lock the 
record, and then delete the record. However, you cannot use the deletion operation to 
delete a global data record. 

For audited databases, the database must be in transaction state to perform a deletion 
operation. 

Notes: 

• This entry point functions in the same manner as does the find 
operation entry point except that a record is locked and deleted 
after it is found. The entry point can locate the record using a 
random, sequential, or combination search. Refer to "Finding 
Records" in this section. 

• The deletion operation leaves an image of the deleted record 
in the user work area. This image is used by the re-create 
operation. See "Re-creating Records" later in this section. 



Passing Parameters 

The standard entry point used to delete a record has three parameters: the direction of 
the retrieval, the name of the data set, and any condition to be used in the search for the 
record. 

Parameter Explanation 

<direction > Identifies the physical sequence for a sequential search . 

<structure> Identifies the structure to be searched. It can be either a data set, 

an index set, or a database. 

<condltion> Gives the special criteria for a random search. 

Only the name of structure is required; the other parameters are optional. If only the 
name is given, the current record is moved to the user work area and deleted. 

Table 3-16 gives the exported names of the entry points, along with the parameters and 
the data type of each parameter. 
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Table 3-16. Deleting a Data Record 



Exported Name of Entry Point 


Parameter 


Data Type of 
Parameter 


ALGOLDELETE 


<clirection> 


STRING 




<structure> 


STRING 




<condition> 


STRING 


DBDELETE 


<direction> 


DISPLAY 




<structure> 


DISPLAY 




<condition> 


DISPLAY 


FORTRAN77DELETE 


<direction> 


CHARACTER 




<structure> 


CHARACTER 




<condition> 


CHARACTER 



Direction 

The direction parameter is part of the serial search. Use the following syntax to identify 
the direction of a sequential search: 

<direction> 



- FIRST -I 

- NEXT - 

- PRIOR - 
L- LAST —J 



The variable elements of the direction parameter are explained as follows: 



Element 

empty or blanks 



FIRST 
NEXT 
PRIOR 
LAST 



Explanation 

(Default) Indicates that the deletion operation does not use a sequential 
search. 

Note: If you leave both the direction and condition 

parameters blank, DMSII transfers the current record 
in ike specified structure to the user work area. 

Transfers the first record in the specified structure to the user work area 
before deleting the record . 

Transfers the next record in the specified structure to the user work area 
before deleting the record. 

Transfers the prior record in the specified structure to the user work area 
before deleting the record. 

Transfers the last record in the specified structure to the user work area 
before deleting the record. 
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structure 



The record must be in a data set. The data set name must be unique. The following 
syntax diagram shows you can use a maximum of 12 qualifying parameters to imiquely 
identify the data set: 



<data set qualified name> 

— <name> 



/12\ 

OF — <name 

~ /12\ 
. — <name>' 




The variable element of the data set name is explained as follows: 
Element Explanation 



<name> 



Identifies tiie data set tliat is searched for the record at run time. The 
name can consist of from 1 to 17 letters, digits, and— depending on the 
language— either underscores (_) or hyphens (-). The first character 
must be a letter. The last character must be either a letter or a digit. 



For example, if your program accesses two databases (DBl and DB2) and each database 
has a data set named CLASS, you must qualify the data set name by naming the 
database. 



Conditions 

Use the following sjmtax to identify any conditions governing a random search: 



<condltlon> 



1— <selection express! on>^ 
1-<1 i nk> ■ ' 

The variable elements of the condition parameter are explained as follows: 
Element Explanation 

empty or blanks (Default) Indicates that the search does not use any selection criteria. 

No^ If you leave both the direction and condition 

parameters blank, DMSII transfers tiie current record 
in specified structure to the user work area. 

<selection Establishes criteria for the search during the deletion operation. (For 

^pression > languages that also support language extensions, consult the reference 

manual for selection expression syntax. Read the DMSII Application 
Programming Guide for a detailed explanation of a selection 
expression.) 

<iink> Identifies the database structure or data set Item that links the cunent 

record to a record in another data set. 
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Deleting Data Records (cont.) 



Programming Examples 

In these program fr^ments, the entry point is used to find the first record in the data 
set EMP in which the EMP-NO is 11. Unless that record is a global data record, it is 
deleted. 



ALGOL Program Fragment 

%Declaring local variables 

STRING 

FIRST_1, 

DATA_SET_NAME, 

CONDITIONS ; 
BOOLEAN 

RSLT 

%Assigning values to parameters 

FIRST_1:=" FIRST"; 

DATA_SET_NAME:="EMP"; 

C0NDITI0N_1:="EMP-N0=11"; 

%Declanng library entry point 

LIBRARY DMI; 

BOOLEAN PROCEDURE DBDELETE(DIRECTION, STRUCTURE, CONDITION) ; 
STRING DIRECTION, STRUCTURE, CONDITION; 
LIBRARY DMI (ACTUALNAME="ALGOLDELETE") ; 

%Invoking entry point 

RS LT : =DBDELETE (FI RST_1 , DATA_SET_NAME ,C0NDITI0N_1) ; 
IF RSLT 

THEN EXCEPTIONHANDLER; 
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C0B0L74 or COB0L85 Program Fragment 

Note: In the following example, the variable RESULT is declared as 
a COMP item, making this example a COBOL74 or COBOL85 
program fragment. If RESULT were declared as a COMP-2 item, 
this fragment could be used in a COBOL program. 

***Decl an* ng variables 



01 FIRST-1 

01 DATA-SET-NAME 

01 CONDITION-1 

01 RESULT 



PIC X(5) VALUE IS "FIRST". 

PIC X(17) VALUE IS "EMP". 

PIC X(9) VALUE IS "EMP-N0=11". 

PIC 9(1) COMP VALUE IS 0. 



•Invoking entry point 



CALL "DBDELETE OF DMINTERPRETER" 

USING FIRST-1, DATA-SET-NAME, CONDITION-1 
GIVING RESULT. 



FORTRAN?? Program Fragment 

***Declanng library entry point 

LOGICAL FUNCTION DBDEL (STR,ITEM,WHERE) 
CHARACTER STR, ITEM, WHERE 

IN LIBRARY DMI (ACTUALNAME = "F0RTRAN77DELETE") 

END 

***Setting variables to initial values 

CHARACTER FIRST *10 /"FIRST"/ 

* DSNAME *4 /"EMP"/ 

* COND *9 /"EMP-N0=»11"/ 

***Declaring local variables 

LOGICAL RSLT 

***Invoking entry point 

RSLT = DBDEL(FIRST,DSNAME.COND) 
IF (RSLT) CALL EXCEPT 
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Re-creating Records 

In existing records, if an item is not required, you can change the value of the item by 
finding and locking the record, moving data from the application program directly into 
the item, and storing the record back in the database. Any item in the original record 
that is not specifically changed remains the same. 

However, if a required item is part of a set in which duplicates are not allowed or if the 
DASDL KEYCHANGEOK option is not set, you must reconstruct the entire record 
and specifically enter the values for all modified items. To modify a required item, yo\ir 
program must do the following: 

1. Delete the original record. 

2. Immediately re-create the record format. 

3. Use the DBPUT data transfer entry points to place values into the re-created 
record. (See Section 4, "Transferring Data," for details of DBPUT entry points.) 
Any item that is not specifically changed remains as it was in the original (deleted) 
record. 

4. Store the newly re-created record in the database while the database is in 
transaction state. 

The re-create operation allows the program to access the user work area in which a 
previously deleted record image resides and to reuse the record. Re-creating can be done 
either in or out of transaction state. However, since a record can be deleted and stored 
only in transaction state, re-creating records in transaction state is more efficient. 



Caution 

When you delete a record, an image of the record format and values remains 
in the user work area. The re-create operation uses this image to re-create the 
record, if your program performs any operation that affects the user worl< area 
after the deletion operation and before the re-create operation, you will not be 
able to re-create the record. 



Passing Parameters 

The standard entry point used to re-create a record has two required parameters: the 
data set qualified name and the record type. 

Parameter Explanation 

<data set Identifies the data set in which the record resides, 

qualified name> 

<record type> Determines whether the duplicated record has a variable or a fixed 

format. (The DMSII Technical Overview has a detailed explanation 
of variable and fixed-format records.) 
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Table 3-17 gives the exported names of the entry points, along vdth the parameters and 
the data type of each parameter. 



Table 3-17. Re-creating a Record 



Exported Name of Entry Point 


Parameter 


Data lype of 
Parameter 


ALGOLRECREATE 


<clata set qualified name> 


STRING 




<recorcl type> 


STRING 


DBRECREATE 


<clata set qualified name> 


DISPLAY 




< record typo 


DISPLAY 


FORTRAN77RECREATE 


<data set qualified name> 


CHARACTER 




<record type> 


CHARACTER 



Data Set Name 

The data set name must be imique. The following syntax diagram shows you can use up 
to 12 quali^nng parameters to uniquely identify the data set: 



<data set qualified name> 

— <name>- 




/12\ 



OF — <name> 

/12\ 
. — <name> 



The variable element of the data set name is e^lained as follows: 
Element Explanation 

Identifies the data set in which the existing record resides. 



<data set 
qualified name> 



The name can consist of from 1 to 17 letters, digits, and -depending on 
the language-either underscores (_) or hyphens (-). The first character 
must be a letter. The last character must be either a letter or a digit. 



For example, if your program accesses two databases (DBl and DB2) and each database 
has a data set named CLASS, you must qualify the data set name by namii^ the 
database. 
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Record Type 

Use the following syntax to identify the record l^e: 



< record type> 



— T— <i nteger>- 
h-<blank> — 



I— <empty string 



The variable elements of the record t3^e parameter are explained as follows: 



Element 

<int^er> 



blank 

empty string 



Explanation 

Creates a variable-format record. An integer is a whole number 
(0123456789) that consists of from 1 to 12 digits and whose maximum 
value can be 549755813887. 

A variable format consists of two parts: a fixed part (header) and a 
variable part (trailer): 

• Entry of a nonzero int^er creates both parts of a variable-format 
record. 

• Entry of a zero (0) creates only the fixed part of a variable-fomiat 
record. 

Creates a fixed-format record. 
Creates a fixed-format record. 



Programming Examples 

The following program fragments re-create a fixed format record in the data set EMB 
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ALGOL Program Fragment 

%Declaring local variables 

STRING 

DATA_SET_NAME, SPACE_1; 
BOOLEAN 

RSLT; 

%Assigning values to parameters 

DATA_SET_NAME:="EMP"; 
SPACEJ:=" 

%Declaring library entry point 
LIBRARY DMI; 

BOOLEAN PROCEDURE DBRECREATE (STRUCTURE, RECORDTYPE) ; 
STRING STRUCTURE, RECORDTYPE; 
LIBRARY DMI (ACTUALNAME="ALGOLRECREATE") ; 

%Invoking entry point 

RSLT : =DBRECREATE (DATA_SET_NAME ,SPACE_1) ; 
IF RSLT 

THEN EXCEPTIONHANDLER; 



C0B0L74 or C0B0L85 Program Fragment 

Note: In the following example, the variable RESULT is declared as 
a COMP item, making this example a COBOL74 or COBOL85 
program fragment. If RESULT were declared as a COMP'2 item, 
this fragment could be used in a COBOL program. 

***Declaring variables 

01 DATA-SET-NAME PIC X(17) VALUE IS "EMP". 

01 SPACE-1 PIC X(l) VALUE IS " 

01 RESULT PIC 9(1) COMP VALUE IS 0. 

***Invoking entry point 

CALL "DBRECREATE OF DMINTERPRETER" 
USING DATA-SET-NAME, SPACE-1 
GIVING RESULT. 
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FORTRAN?? Program Fragment 

***Declaring library entry point 
«icomp> 

LOGICAL FUNCTION DBRCR (STR, RECTYP) 
CHARACTER STR. RECTYP 

IN LIBRARY DMI (ACTUALNAME = "F0RTRAN77 RECREATE") 
END 

***S^tting variables to initial values 

CHARACTER DSNAME *4 /"EMP"/, 
* SPACE *1 /" "/ 

***Declaring local variables 

LOGICAL RSLT 

***Invoking entry point 

RSLT = DBRCR (DSNAME. SPACE) 
IF (RSLT) CALL EXCEPT 
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Storing Records 

You must use a store operation to enter a newly created, re-created, or modified record 
into a specified structure. The store operation also makes the appropriate entries into 
each set associated with the data set. 



Only records that have been placed into the work area of the program by a lock, create, 
re-create, or store operation can be stored. 

Note: You can store a record in an audited database only when the program 
is in transaction state. 

Passing a Parameter 

The standard entry point used to store a record has one required parameter— the name 
ofthe data set or database. . 

Parameter Explanation 

<structure> Identifies either the data set or the database where the record Is to be 

stored. 

Table 3-18 gives the exported names of the entry points, along with the parameter and 
the data type of the parameter. 



Table 3-18. Storing Records 







Data Type of 


Exported Name of Entry Point 


Parameter 


Parameter 


ALGOLSTORE 


<structure> 


STRING 


DBSTORE 


<structure> 


DISPLAY 


FORTRAN77STORE 


<structure> 


CHARACTER 



The structure can be dtiier a data set or a database. The following syntax diagrams 
show if the name ofthe data set is not unique, you can use up to 12 qualifying 
parameters to uniqudy identify the data set. A database name cannot be qualified. 



<structure> 



I — <di 
l-<d 



data set qualified name>- 
atabase nanie> — 



<data set qualified name> 

— <naine>- 



/12\ 



OF — cname> 
— /12\ - 
. — <name: 
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The variable element of the structure parameter is explained as follows: 



Element 



Explanation 



<data set 
qualified name> 



Identifies the data set in which the record will be stored. The data set 
must be defined as a data set within the specified database. 



<database 
name> 



Identifies the database for which the DM INTERPRETER library was 
compiled. The stored infomriation is stored in the global record for the 
database. 



<name> 



Identifies the name of the data set or database. A name can consist of 
from 1 to 17 letters, digits, and— depending on the language— either 
underscores (_) or hyphens {-). The first character must be a letter. The 
last character must be either a letter or a digit. 



For example, if your program accesses two databases (DBl and DB2) and each database 
has a data set named CLASS, you must qualify the data set name by naming the 
database. 

Programming Examples 

The following program fragments show how to store a record in a data set named EMP 



ALGOL Program Fragment 

%Declaring local variables 

STRING 

DATA_SET_NAME; 
BOOLEAN 

RSLT; 

%Assigning values to parameters 
DATA_SET_NAME : =" EMP" ; 
%Declanng library entry point 
LIBRARY DMI; 

BOOLEAN PROCEDURE DBSTORE (STRUCTURE); 
STRING STRUCTURE; 

LIBRARY DMI (ACTUALNAME="AL60LST0RE») ; 

%Invoking entry point 

RSLT:=DBSTORE(DATA_SET_NAME) ; 
IF RSLT 

THEN EXCEPTIONHANDLER; 
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C0B0L74 or C0B0L85 Program Fragriient 

Note: In the following excanple, the variable RESULT is declared as 
a COMP item, making this example a COBOL74 or COBOL85 
program fragmjent If RESULT were declared as a COMP-2 item, 
this fragmjent could be used in a COBOL program. 

***Declaring variables 

01 DATA-SET-NAME PIC X(17) VALUE IS "EMP". 

01 RESULT PIC 9(1) COMP VALUE IS 0. 

***Invoking entry point 

CALL "DBSTORE OF DMINTERPRETER" 
USING DATA-SET-NAME 
GIVING RESULT. 



FORTRAN?? Program Fragment 

***Declaring library entry point 

LOGICAL FUNCTION DBSTORE (STR) 
CHARACTER STR 

IN LIBRARY DMI (ACTUALNAME = "FORTRAN77STORE") 

END 

***Setting variables to initial values 

CHARACTER DSNAME *4 /"EMP"/ 

***Declaring local variables 

LOGICAL RSLT 

★★★Invoking entry point 

RSLT = DBSTORE (DSNAME) 
IF (RSLT) CALL EXCEPT 
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End Transaction — Leaving Transaction State 

When transactions are completed, the end transaction operation takes the audited 
database out of transaction state and placed the database a protected state. In the 
protected state, no update activity can be performed. 

Note: DMSII ignores invocations to begin or end transaction state for 
unaudited databases. 

Posing a Parameter 

The standard entry point used to leave transaction state has one required 
parameter— the audit syncpoint parameter. 

Parameter Explanation 

<auditsync> Specifies whetlier an image of the current restart data set is to t)e 

audited and can force a syncpoint. 

Tlie restart data set is used for restart routines. A syncpoint minimizes 
application recovery time by controlling how often the database is forced 
to t)e synchronized with the audit trail. (Consult the DMSII Technical 
Overview, the DMSII DASDL Reference Manual, and the 
DMSII Application Programming Guide for details about restart 
data sets and syncpoints.) 

Table 3-19 gives the exported names of the entry points, along with tiie parameter and 
the data type of the parameter. 



Table 3-19. End Transaction — Leaving Transaction State 







Data Type of 


Exported Name of Entry Point 


Parameter 


Parameter 


ALGOLEN DTRANSACTION 


<auditsync> 


STRING 


DBENDTRANSACTION 


<audltsync> 


DISPLAY 


F0RTRAN77ENDTRANSACTI0N 


<auditsync> 


CHARACTER 



Use the following sjnatax to end transaction state: 



<audit^c> 

— <audit> 



L SYNC -I 
<audit> 



i- AUDIT J 

L NOAUDIT -J 
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Leaving Transaction State (cont.) 



The elements of the audit s;yncpoint parameter are explained as follows: 



Element 



Explanation 



empty or blanks 



(Default) NOAUDIT assumed. 



AUDIT 



Audits an image of the current restart data set record. 



NOAUDIT 



No auditing occurs. 



SYNC 



Forces a syncpoint after the transaction Is successfully completed. 



Use the SYNC option in an end transaction operation to override the syncpoint option 
set in the DASDL description of the database. The end transaction operation should be 
immediately followed by recovery code. 

You can use the SYNC option with either the AUDIT or NOAUDIT option; both AUDIT 
SYNC and NOAUDIT SYNC are valid. 



Programming Examples 

The foUowing program fragments cause a program to exit transaction state with the 
current restart data set record being audited. In these instances, your program must set 
a variable to AUDIT or AUDIT SYNC before invoking the entry point. 

ALGOL PK^[ram Fragment 

%Declaring local variables 

STRING 

P__AUDIT; 
BOOLEAN 

RSLT; 

%Assigning values to parameters 
PLAUDIT: AUDIT"; 
%Declanng library entry point 
LIBRARY DMI; 

BOOLEAN PROCEDURE DBENDTRANSACTION (AUDITSYNC); 
STRING AUDITSYNC; 

LIBRARY DMI (ACTUALNAME="ALGOLENDTRANSACTION") ; 

%Invoking entry point 

RSLT:=DBENDTRANSACTION (P__AUDIT) ; 
IF RSLT 

THEN EXCEPTIONHANDLER; 
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Leaving Transaction State (cont.) 



C0B0L74 or C0B0L85 Program Fragment 

Note: In the following example, the variable RESULT is declared as 
a COMP item, making this example a COBOL74 or COBOL85 
program fragment. If RESULT were declared as a COMP-2 item, 
this fragment could he used in a COBOL program. 

***Declanng variables 

01 P-AUDIT PIC X(5) VALUE IS "AUDIT". 
01 RESULT PIC 9(1) COMP VALUE IS 0. 

***Invoking entry point 

CALL "DBENDTRANSACTION OF DMINTERPRETER" 
USING P-AUDIT 
GIVING RESULT. 



FORTRAN?? Program Fragment 

***Declaring library entry point 

LOGICAL FUNCTION DBETR (AUDIT) 
CHARACTER AUDIT 

IN LIBRARY DMI (ACTUALNAME = "FORTRAN77ENDTRANSACTI0N") 
END 

***Setting variables to initial values 

CHARACTER AUDIT *10 /"AUDIT"/ 

***Declaring local variables 

LOGICAL RSLT 

***Involcing entry point 

RSLT = DBETR(AUDIT) 
IF (RSLT) CALL EXCEPT 
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Closing a DMSII Database 

After closing a DMSII database, your application program can no longer access any of the 
files associated with the database. Althou^ the database is implicitly closed when the 
library execution is complete, explicitly closing the database is a recovery safeguard. 

Note: Do not close a database when the database is in transaction state. 

The transaction state should be explicitly exited before the database is 
closed. See "End Transaction— Leaving Transaction State" in this 
section. 

Passing Parameters 

The standard entry point that explicitly closes the database has no required parameters. 
Table 3-20 gives the exported names of the entry points. 

Table 3-20. Export Names of Entry Points Used to Close a Database 



Export Names 

ALGOLCLOSE 
DBCLOSE 

FORTRAN77CLOSE 



Programming Examples 

The following program fragments dose a database. 

ALGOL Pr<^am Fragment 

Note: You do not need to assign ALGOLCLOSE values to parameters in 
order to use the ALGOLCLOSE entry point. 

%Declar1ng local variables 

BOOLEAN 
RSLT; 

%Declanng library entry point 
LIBRARY DMI; 

BOOLEAN PROCEDURE DBCLOSE; 

LIBRARY DMI (ACTUALNAME="ALGOLCLOSE") ; 

%Invok1ng entry point 

RSLT:=DBCLOSE; 
IF RSLT 

THEN EXCEPTIONHANDLER; 
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Closing a DMSII Database (cont.) 



C0B0L74 or C0B0L85 Program Fragment 

Note: In the following example, the variable RESULT is declared as 
a COMP item, making this example a COBOL74 or COBOL85 
program fragment. If RESULT were declared as a COMP-2 item, 
this fragment could he used in a COBOL program. 

***Decl an" ng vari abl es 

01 RESULT PIC 9(1) COMP VALUE IS 0. 

***Invoking entry point 

CALL "DBCLOSE OF DMINTERPRETER" 
GIVING RESULT. 



FORTRAN?? Pr(^am Fragment 

Note: You do not need to set FORTRAN77CLOSE variables to initial 
values in order to use the FORTRAN77CLOSE entry point. 

***Declaring library entry point 

LOGICAL FUNCTION DBCLOSE () 

IN LIBRARY DMI (ACTUALNAME = "F0RTRAN77CL0SE'') 

END 

***Declaring local variables 

LOGICAL RSLT 

***Invoking entry point 

RSLT = DBCLOSE ( ) 

IF (RSLT) CALL EXCEPT 
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Executing Language Extensions 

You can execute language extensions through a standard entry point. The entry point 
allows flexible, run-time definition of DMSII operations and provides users with an easy 
transition from DMSII language extensions. However, because the input to this entry 
point must be completely parsed, the entry point runs at hi^er processor cost. 

Passing a Parameter 

As seen in Table 3-21, there is one required parameter— the language exte^ion 
statement. This parameter must evaluate to a complete statement. Exception actions 
and input and output mapping are not allowed. 

Note: FORTRAN?? does not support the DMSII language extensions 

interface. However, you can use the FORTRAN?7VERB entry point. 



Table 3-21. Executing Language Extensions 



Exported Name of Entry 




Point 


Parameter 


ALGOLVERB 


< language extension statement> 


DBVERB 


< language extension statement> 


F0RTRAN77VERB 


< language extension statement> 



The following DMSII user language constructs can be used as the required parameter: 
Datat)ase statement Set statement 

Create statement Search statement 

Transaction statement Status statement 

Record statement 

Brief de^^ptions of these statements are included here. If your application language 
supports the DMSII language extensions, consult the appropriate language-specific 
reference mamffil for more information. 

Database Statement 

A database statement performs one of two functions: 

• Closes the database 

• Opens the database for either mquixy or inquiry and update 
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Executing Language Extensions (cont.) 



<database statement> 



— T- CLOSE 
«- OPEN - 



- INQUIRY 
UPDATE — ' 



Create Statement 

A create statement initializes the user work area for a new or re-created image of a data 
set record. 



<create statement> 



T- CREATE r-<data set>— p- 

L RECREATE -I L 



( — <integer> — ) 



J 



Transaction Statement 

A transaction statement causes a program to either enter or exit transaction state, with 
or without auditing an image of the ctirrent restart data set and forcing a syncpoint. If a 
name is specified, it is the restart data set. 



<transaction statement> 

BEGINTRANSACTION -,-<audit>- 



L name: 

ENDTRANSACTION TT-<audit> 

L- <name>- 
h BEGIN-TRANSACTION 



L 



<narae>- 
audit>— 



U NO-AUDIT H 
AUDIT — 



I— <name>— ^ 
<audit> — ' 

<name> 



SYNC 



>- END-TRANSACTION 



NO-AUDIT 
AUDIT — 



-<name>- 



L 



SYNC -I 



Record Statement 

A record statement performs one of two fimctions: 

• Stores a new or modified record in a specified structure 

• Unlocks a record residing in a specified structure 

<record stateiiient> 

— p- STORE — r-<structure> 

L FREE — » 



Set Statement 

A set statement sets the current path of a specified structure to the start or end of the 
structure or, if it is an index set, to a particular data set. 
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Executing Language Extensions (cont.) 



<set statement> 

— SET — <structure> — TO — <target> -| 

Search Statement 

A search statement finds a selected record in a specified structure and locks the record 
for modification or deletion. 



<search statement> 



FIND - 

- LOCK - 

- MODIFY - 
L DELETE -! 



h FIRST -1 
LAST - 
NEXT - 
- PRIOR -J 
'-<data set 



-<structure>- 



- WHERE 
1- AT — 



— r-<expressi 



ons 



VIA 



slinks- 



Status Statement 

A status statement allows the user to find out whether a prior database operation was 
successful. 



<statu$ statement> 

— DMSTATUS 1 

Notes: 

• The COBOL, COBOL74, and COBOL85 languages cannot use 
the DMSTATUS form of a call on DBVERB. These languages 
cannot pass an exception parameter. Instead, use a direct call 
on the DBSTATUS entry point. 

• The ALGOL and FORTRAN?? languages, when using the 
status statement construct, pass only the string DMSTATUS as 
a parameter. In all other cases, ALGOL programs use complete 
user language interface statemente. 
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Programming Examples 

The following program fragments show how the entry point can be called to execute the 
set, search, and status language extensions. 

ALGOL Program Fragment 

Note: You do not need to declare local variables or assign values to 

parameters that pertain to the DBVERB when you use the DBVERB 
to execute set, search status language extensions in ALGOL. 

%Declan'ng library entry point 
LIBRARY DMI; 

BOOLEAN PROCEDURE DBVERB (HOSTSTATEMENT); 
STRING HOSTSTATEMENT; 
LIBRARY DMI (ACTUALNAME="ALGOLVERB") ; 

%Invoking entry point 
% 

% USING DBVERB ON A SET STATEMENT 
% 

RSLT:=DBVERB("SET EMP TO BEGINNING"); 
IF RSLT 

THEN EXCEPTIONHANDLER; 

% 

% USING DBVERB ON A SEARCH STATEMENT 
% 

RSLT:=DBVERB("FIND FIRST EMP AT EMP-NO"); 
IF RSLT 

THEN EXCEPTIONHANDLER; 

% 

% USING DBVERB ON A STATUS STATEMENT 
% 

DBVERB ("FIND PRIOR EMP"); 
RSLT:=DBVERB{"DMSTATUS") ; 
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COBOL, C0B0L74, or C0B0L85 Program Fragment 
***Decl ari ng vari abl es 

01 DATA-REQUEST PIC X(40} VALUE IS SPACES. 

***Invol(ing entry point 
** 

** USING DBVERB ON A SET STATEMENT 
** 

MOVE "SET EMP TO BEGINNING" TO DATA-REQUEST. 
CALL "DBVERB OF DMINTERPRETER" 

USING DATA-REQUEST 

GIVING RESULT. 
IF RESULT = 1 

PERFORM EXCEPTION-HANDLER. 

** 

** USING DBVERB ON A SEARCH STATEMENT 
** 

MOVE "FIND FIRST EMP AT EMP-N0=11" TO DATA-REQUEST. 
CALL "DBVERB OF DMINTERPRETER" 

USING DATA-REQUEST 

GIVING RESULT. 
IF RESULT = 1 

PERFORM EXCEPTION-HANDLER. 
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Executing Language Extensions (cont.) 



FORTRAN?? Program Fragment 

Note: You do not have to set any variables that pertain to the DBVERB to 
initial values when you use the DBVERB to execute set, search status 
language extensions in FORTRAN??. 

***Declaring library entry point 

LOGICAL FUNCTION DBVERB (STMT) 
CHARACTER STMT 

IN LIBRARY DMI (ACTUALNAME = "FORTRAN? 7 VERB") 

END 

***Declanng local variables 

LOGICAL RSLT 

***Invoking entry point 

* USING DBVERB ON A SET STATEMENT 

RSLT = DBVERB ("SET EMP TO BEGINNING") 
IF (RSLT) CALL EXCEPT 



* USING DBVERB ON A SEARCH STATEMENT 

RSLT = DBVERB ("FIND FIRST EMP AT EMP-N0=11") 
IF (RSLT) CALL EXCEPT 

* USING DBVERB ON A STATUS STATEMENT 

RSLT = DBVERB("SET EMP TO BEGINNING") 

IF (RSLT) CALL EXCEPT 

RSLT = DBVERB ("FIND PRIOR EMP") 

RSLT = DBVERB ("DMSTATUS") 

CALL DBEXCN(RSLT,MSG) 

CALL DBEXCT (RSLT, MSG) 
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Section 4 
Transferring Data 



With the DMSn langueige extensions interface, any program written in a supported 
COBOL language can directly access data in the database. All other languages must use 
input and output mapping statements. Direct access is available because the COBOL 
compilers can access the DASBL database description during program compilation 
and can enforce data-type checking. In contrast, any compiler in which formal data 
structures are not directly supported cannot enforce data-t57pe checking. 

With the interpretive interface, direct access to data is not possible through any 
language compiler for these reasons: 

• The compiler might not be able to enforce data-type checking in all situations. 

• The format of a user work area might not be known during program compilation. 

Instead of accessing the data directly, the interpretive interface uses data transfer entry 
points, provided through the DMINTERPRETER library, to access and move data. The 
DBGET and DBPUT data transfer entry points move data into and out of a user work 
area. 

Each data transfer task, with its corresponding entry points, are listed in Table 4-1. Use 
the heading for each listed data transfer task to locate the pages that detail the entry 
point. For example, a description of the data transfer entry points ALGOLGETSTMNG, 
DBGETDISPLAY, and FORTRAN77GETCHARACTER is found under, "Moving 
Character Strings to Variables." The tasks are grouped; aU DBGET data entry points 
are presented before all DBPUT data entry points. Constructing data transfers during 
program execution is explained as the last data entry point. General guidelines for using 
the data entry points precede the task descriptions. 



Table 4-1. Data Entry Points to the DMINTERPRETER Library by Task 



Task 


Entry Points 


Moving ciiaracter strings to variables 


ALGOLGETSTRING 




DBGETDISPLAY 




F0RTRAN77G ETCH ARACTER 


Moving Kanji aiplia character stringy to variables 


ALGOLGETKANJI 




DBGETKANJI 




F0RTRAN77GETKANJI 



continued 
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Transferring Data 



Table 4-1. Data Entry Points to the DMINTERPRETER Library by Task (cent.) 



Task 


Entry Points 


Moving numeric values to variables 


ALGOLGETREAL 

DBGETREAL 

FORTRAN77GETREAL 


Moving double-precision values to variables 


ALGOLGETDOUBLE 

DBGETDOUBLE 

FORTRAN77GETDOUBLE 


Retrieving Boolean values 


ALGOLGETBOOLEAN 

DBGETBOOLEAN 

FORTRAN77GETLOGICAL 


Placing strings into data items 


ALGOLPUTSTRING 

DBPUTDISPLAY 

FORTRAN77PUTCHARACTER 


Placing strings into Kanji alpha items 


ALGOLPUTKANJI 

DBPUTKANJI 

FORTRAN77PUTKANJI 


Placing numeric values into data items 


ALGOLPUTREAL 
DBPUTREAL 

FORTRAN77PUTCHARACTER 


Placing double-precision values into data items 


ALGOLPUTDOUBLE 

DBPUTDOUBLE 

FORTRAN77PUTDOUBLE 


Setting data items to Boolean values 


ALGOLPUTBOOLEAN 
DBPUTBOOLEAN 

FORTRAN77PUTLOGICAL 


Setting data items to a null value 


ALGOLPUTNUL 

DBPUTNULL 

F0RTRAN77PUTNULL 


Constructing data transfers during program execution 


ALGOLDATA 
DBDATA 

FORTRAN77DATA 
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The discussion of each task includes the following: 

• A brief explanation of the function of the entry point 

• Syntax diagrams and semantics that describe required parameters 

• Program fragments that illustrate 

- Declaring variables for the entry points 

- Invoking the entry point 

- Returning results from the DMINTERPRETER Ubrary 

Unless specifically noted, COBOL, COBOL74, and COBOL85 have the same 
requirements. 

Guidelines for Using Data Transfer Entry Points 

DBGET and DBPUT data transfer entry points operate on data in the follovong manner: 

• DBGET entry points move data from the user's work area to user-declared 
variables. The DBGET entry points return an exception if the declared variable is 
too short to hold the specified data item. 

• DBPUT entry points move data from user-declared variables to user work areas. 
The DBPUT entry points return an exception if the value to be put into the database 
does not fit into the specified data item. 

As illustrated in Figure 4-1, modifying the database with the interpretive interface 
resembles the following three-step process: 

1. Prepare the user work area in one of two ways: 

• Use a find, delete, lock or secure operation to retrieve and move data fi*om an 
existing record to the user work area. 

• Use a create or re-create operation to reserve space in the user work area. 

2. Use the DBPUT and DBGET data transfer entry points to transfer values between 
the program and the work area. 

3. Use the store operation to transfer data from the user work area back to the 
database. 



8600 0155-000 



4-3 



Transferring Data 



r 



STEP 1 



r 



STEP 2 



r 



STEP 3 < 




DMSII 
User Work Area 



GET 



PUT 



User-Declared 
Variables 



DMSII 
User Work Area 



STORE 



DMSII 
I Database 



Figure 4-1. Three Steps in Transferring Data 



The DMINTERPKETER library checks the parameters of data transfer entry points to 
ensure that the requested operation is compatible vdth the DASDL database description. 
For example, items declared in the DASDL description with an OCCUBS clause must be 
subscripted. 
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Transferring Data 



For more information read the following sections: 

• Section 2, "Accessing the Interpretive Interface," details how each language accesses 
the interpretive interface and how each language invokes an entry point. 

• Section 3, "Manipulating the Database," explains how to find, lock, create, re-create, 
and store records. 

• Section 5, "Handling Exceptions," contains detailed information on exception 
handling. 

• Appendix B, "DMSII Exceptions and Errors," contains the spediic messages for the 
DBGET and DBPUT exceptions. 
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Moving Character Strings to Variables 

You can move the content of an alpha or a group item character string to a 
program-declared variable, using a DBGET data transfer entry point. 

Passing Parameters 

The data transfer entry points that move character strings to variables have three 
required parameters: the name of the structure, the name of the itemi, and the name of 
the variable. 

Parameter Explanation 

<structure> Identifies either the data set (for an alpha Item) or the database (for a 

global item) in which the item is located. 

< item name> Identifies the data set item whose string value is to be moved to the 

user-declared variable. 

<variable name> Identifies the user-declared variable by its name in the program. The 
variable must be able to contain a string. 

Table 4-2 gives the exported names of the entry points, as well as the parameters and 
the data type of each parameter. 



Table 4-2. Moving Character Strings to Variables 



Exported Name of Entry Point 


Parameter 


Data T;^ of 
Parameter 


ALGOLGETSTRING 


<structure> 


STRING 




<ltem name> 


STRING 




<varlable name> 


STRING 


DBGETDISPLAY 


<structure> 


DISPLAY 




<item name> 


DISPLAY 




<variable name> 


DISPLAY 


F0RTRAN77GETCHARACTER 


<structure> 


CHARACTER 




<item name> 


CHARACTER 




<variable name> 


CHARACTER 



Structure 

The structure can be either a data set or a database. The followii^ syntax diagrams 
show tibat if the name of the data set is not unique, you can use up to 12 qualifying 
parameters to uniquely identify the data set. A database name cannot be qualified. 
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Moving Character Strings to Variables (cont.) 



<$tructure> 



-p-<data set qualified names- 
L-<:database name> — : 



<data set qualified name> 
— <name>- 



/12 \ 

_i_ OF — <name 

■« /12\ 

— . — <name> 



The variable elements of the structure parameter are explained as follows: 
Element Explanation 

<data set Identifies tiie data set in wlilch tlie aipiia item is located, 

qualified name> 

<database Identifies tiie database In wiiich tlie global data item is located. 

name> 

<name> Identifies the name of tiie data set or database. A name can consist of 

from 1 to 17 letters, digits, and-depending on the language-elther 
underscores (_) or hyphens (-). The first character must be a letter. The 
last character must be either a letter or a digit. 



Itenn Name 



The following syntax diagrams show the valid combinations of characters that can be 
used to form an item name: 



<item name> 

Lindersc< 
^lyphen name> 



p<underscore name>-T- 

I — <hynh^n naniA> 1 



[ — L-<i nteger>-'— ] 
nteger>— 1— ) 



< underscore name> 



sletter>- 



/15\ -i-<1etter>- 
h-<digit>- 



-|— «:letter>-j 
i-<digit> — ' 



<underscore5 



< hyphen name> 



!letter>- 



<1 etter> 



/15\ -|-<letter>^^ 
U<digit> — 
I— <hvDhen5^ 



I— <digit 
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The variable elements of an item name are explained as follows: 



Element 



Explanation 



< underscore 
name> 



A string of from 1 to 17 letters, digits, and underscores (_), starting with 
a letter and ending with either a letter or a digit. 



< hyphen name> 



A string of from 1 to 17 letters, digits, and hyphens (-), starting with a 
letter and ending with either a letter or a digit. 



<int^er> 



A subscript for an OCCURS clause item. An int^er Is a whole number 
(0123456789) that consists of from 1 to 12 digits and that has a 
maximum value of 549755813887. 



Variable Name 

Each language has a different way of identifying the variable that contains or evaluates 
to the string. Consult the appropriate language reference manual for more information 
on variables that can contain a string. 

Program Essutnples 

The following program fragments use data transfer entry points to move character 
strings from the user work area to variables declared in the application program. 

ALGOL Pr(^m Fragment 

In the ALGOL example, the data set name (the structure) is initialized as BMP at the 
beginning of the program. The item name is set to EMP_FNAME before the entry point 
is invoked. The variable is set to EXPR_3 in body of the program. 
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Moving Character Strings to Variables (cont.) 



%Declaring local variables 
STRING 

DATA_SET_NAME, ITEM_NAME, EXPR_3; 
BOOLEAN 
RSLT; 

%Ass1gn1ng values to parameters 
DATA_SET_NAME:="EMP"; 
%Declaring library entry point 



LIBRARY DM I; 

BOOLEAN PROCEDURE DBGETSTRING(STRUCTURE. ITEM, VARIABLE) ; 
STRING STRUCTURE, ITEM; 
REAL VARIABLE; 

LIBRARY DMI (ACTUALNAME="ALGOLGETSTRING") ; 



%Invoking entry point 



ITEM_NAME : =" EMP_FNAME" ; 

RSLT:=DBGETSTRING(DATA_SET_NAME, ITEM_NAME,EXPR_3) ; 
IF RSLT 

THEN EXCEPTIONHANDLER; 



C0B0L74 or C0B0L85 Program Fragment 



In the foUovdng example, the structure is declared as EMP at the begmning of the 
program. The item name is set to EMP-FNAME before the entry point is invoked. The 
variable is set to VAB-3 in body of the program. 

Note: In this example, the variable RESULT is declared as a COMP item, 
making this example a COBOL74 or COBOL85 program fragment. 
If RESULT were declared as a COMP-2 item, this fragment could be 
used in a COBOL program. 



***Decl ari ng vari abl es 

01 DATA-SET-NAME 

01 ITEM-NAME 

01 VAR-3 

01 RESULT 



PIC X(17) VALUE IS "EMP". 
PIC X(17) VALUE IS SPACES. 
PIC X(10) VALUE IS SPACES, 
PIC 9(1) COMP VALUE IS 0. 



***Invoking entry point 



MOVE "EMP-FNAME" TO ITEM-NAME. 

CALL "DB6ETDISPLAY OF DMINTERPRETER" 

USING DATA-SET-NAME, ITEM-NAME, VAR-3 

GIVING RESULT. 
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r 



FORTRAN?? Program Fragment 

In this FORTRAN?? example, the structure is set to EMP through the variable 
DSNAME. The item name is assigned before the entry point is invoked. The variable is 
set to EXPR3 in the body of the program. 

***Dec1anng library entry point 

LOGICAL FUNCTION DB6ETC (STR, ITEM, VAR) 
CHARACTER STR, ITEM, VAR 

IN LIBRARY DMI (ACTUALNAME = "F0RTRAN77GETCHARACTER") 
END 

***Setting variables to initial values 
CHARACTER DSNAME *4 /"EMP"/, 



***Declaring local variables 

LOGICAL RSLT 

***Invoking entry point 

ITMNAM = "EMP-FNAME" 

RSLT = DB6ETC (DSNAME, ITMNAM, EXPR3) 

IF (RSLT) CALL EXCEPT 



* 



ITMNAM 
EXPR3 



*13 
*22 



* 
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Moving Kanji Alpha Character Strings to Variables 

You can move the content of a Kanji alpha character string to a program-declared 
variable, using a GETKANJI data transfer entry point. 

Passing Parameters 

The GETKANJI entry points have three required parameters: the name of the 
structure, the name of the item, and the name of the variable. 

Parameter Explanation 

<structure> Identifies the data set or tfie database In which the Item Is located. 

<item name> identifies the data set item whose Kanji string value is to be moved to 

the user-declared variable. 

<varlable name> Identifies the user-declared variable by Its name in the program. The 
variable must be able to contain a Kanji string. 

Table 4-3 gives the exported names of the entry points, as well as the parameters and 
the data type of each parameter. 



Table 4-3. Moving Kanji Character Strings to Variables 



Exported Name of Entry Point 


Parameter 


Data Type of 
Parameter 


ALGOLGETKANJI 


<structure> 


STRING 




<item name> 


STRING 




<variabie name> 


STRING 


DBGETKANJI 


<structure> 


DISPLAY 




<ltem name> 


DISPLAY 




<varlable name> 


DISPLAYor 
KANJI 


FORTRAN77GETKANJI 


<structure> 


CHARACTER 




<item name> 


CHARACTER 




<variable name> 


CHARACTER 



Structure 

The structure can be either a data set or a database. The following syntax diagrams 
show that if the name of the data set is not unique, you can use up to 12 qualifying 
parameters to uniquely identify the data set. A database name cannot be quaMed. 
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Moving Kanji Alpha Character Strings to Variables (cont.) 



<structure> 

I— <( 



:data set qualified name>-r- 
database naine> ' 



<data set qualified name> 





f /12\ 1 


1 




— OF — <name>— L- 






r^/12\-^ 






1—1- . — <name>— ' — ' 





The variable elements of the structure parameter are explained as follows: 
Element Explanation 

Identifies tlie data set that is to be accessed at run time. 



<data set 
qualified name> 

< data base 
name> 

<name> 



Identifies the datatwse for whicli the DMINTERPRETER library was 
compiled. 

Identifies the name of the data set or database. A name can consist of 
from 1 to 17 letters, digits, and-depending on the language-either 
underscores (_) or hyphens (-). The first character must be a letter. The 
last character must be either a letter or a digit. 



Item Name 

The following syntax diagrams show the valid combinations of characters that can be 
used to form an item name: 



<ltem name> 



-T-<underscore name>- 
l— <liyphen name> 



irjteger>— ] 
— ( — J— <i nteger>-L- ) 



<under$core name> 
— <letter>- 



J- /i5\ — -<ietter^ ■ 
|-<digit> 



L-<underscore5 



-r-<l etter>— 
<digit>- 



< hyphen name> 
— <1 etter>- 



/15\ -p<letter> 
h-<digit>- 
L-<hyphen> 



T-<1etter>-H 
L-<digit> — I 
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The variable elements of a name are explained as follows: 



Element 



Explanation 



< underscore 



A string of from 1 to 17 letters, digits, and underscores (_), starting witfi 
a letter and ending with either a letter or a digit. 



name> 



< hyphen name> 



A string of from 1 to 17 letters, digits, and hyphens (-), starting with a 
letter and ending with either a letter or a digit. 



<integer> 



A subscript for an OCCURS clause item. An int^er is a whole number 
(0123456789) that consists of from 1 to 12 digits and that has a 
maximum value of 549755813887. 



Variable Name 

Each language has a different way of identifying the variable that contains or evaluates 
to a Kanji string. Consult the appropriate language reference manual for more 
information on variables that can contain a string. 

Note: COBOL does not support Kanji characters. In COBOL74 and 

COBOL85, where Kanji is supported, the variable can he defined as 
PIC X(2n) or PIC X(n) USAGE IS KANJI. 

Program Examples 

The following program fragments use GETKANJI data transfer entry points to move 
Kanji items from the user work area to variables declared in the application program. 

ALGOL Pr(^am Fragment 

In the ALGOL example, the structiu>e is EMI^ the item name is £MP_KNAME, and the 
variable is EXPR_3. 
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Moving Kanji Alpha Character Strings to Variables (cont.) 



%Declaring local variables 
STRING 

DATA_SET_NAME, ITEM_NAME, EXPR_3; 
BOOLEAN 
RSLT; 

%Assigm"ng values to parameters 
DATA_SET_NAME:="EMP"; 
%Declaring library entry point 



LIBRARY DMI; 

BOOLEAN PROCEDURE DBGETKANJI (STRUCTURE, ITEM,VARIABLE) ; 
STRING STRUCTURE, ITEM; 
REAL VARIABLE; 

LIBRARY DMI (ACTUALNAME="AL60LGETKANJI") ; 
%Invoking entry point 
ITEM_NAME:="EMP_KNAME" ; 

RS LT : =DBGETKANJ I {DATA_SET_NAME , ITEM_NAME . EXPR__3) ; 
IF RSLT 

THEN EXCEPTIONHANDLER; 

C0B0L74 or C0B0L85 Program Fragment 

In this example, the structure is EME* the item name is EMP-KNAME, and the variable 
is VAB-1. The variable RESULT is declared as a COMP item, making this example a 
COBOL74 or COBOL85 program fragment. 

Note: COBOL does not support Kcaiji characters. 
***Decl ari ng vari abl es . 

01 DATA-SET-NAME PIC X(17) VALUE IS "EMP". 

01 ITEM-NAME PIC X(17) VALUE IS SPACES. 

01 VAR-1 PIC X(10) USAGE IS KANJI. 

VALUE IS SPACES. 

01 RESULT PIC 9(1) COMP VALUE IS 0. 



***Invoking entry point 

MOVE "EMP-KNAME" TO ITEM-NAME. 
CALL "DBGETKANJI OF DMINTERPRETER" 

USING DATA-SET-NAME, ITEM-NAME, VAR-1 

GIVING RESULT. 
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FORTRAN?? Program Fragment 

In this FORTRAN?? example, the structure is EMI> the item name is EMP-KNAME, 
and the variable is EXPR3. 

***Declaring library entry point 

LOGICAL FUNCTION DBGETK (STR, ITEM, VAR) 
CHARACTER STR, ITEM, VAR 

IN LIBRARY DMI (ACTUALNAME = "FORTRAN77GETKANJr') 
END 

***Setting variables to initial values 

CHARACTER DSNAME *4 /"EMP"/, 

* ITMNAM *13 

* EXPR3 *22 

***Declaring local variables 

LOGICAL RSLT 

***Invoking entry point 

ITMNAM = "EMP-KNAME" 

RSLT = DBGETK (DSNAME, ITMNAM, EXPR3) 

IF (RSLT) CALL EXCEPT 
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Moving Numeric Values to Variables 

You can transfer the numeric value of a number, real, field, count, record-type, or 
population item to a program-declared variable, using a 6ETREAL data transfer entxy 
point. 



Passing Parameters 

The GETREAL entry points have three required parameters: the name of the structure, 
the name of the item, and the name of the variable. 

Parameter Explanation 

<structure> Identifies tlie data set or the database in which the item is located. 

<item name> Identifies the data set item whose numeric value is moved to the 

user-declared variable. 

<variable name> Identifies the user-declared variable by its name in the program. The 
variable must be able to contain a real value. 

Notes: 

• If the declared variable is too small to hold the specified 
data item, the variable is set to HIGH-VALUE (the largest 
integer that can be represented) and an appropriate exception 
is returned. Corasw/^ ^/le DMSH Technical Overview /or ara 
explanation of HIGH-VALUE. Read Appendix B, "DMSU 
Eocceptions and Errors, " for more information on exceptions. 

• If the numeric items that are too large to be transferred by 
ALGOLGETREAL, DBGETREAL, or FORTRAN77GETREAL, 
use theALGOLGETDOUBLE, DBGETREAL, or 
FORTRAN77GETDOUBLE entry point, respectively. 

Table 4-4 gives the escorted names of the entry points, as well as the parameters and 
the data type of each parameter. 
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Table 4^. Moving Numeric Values to Variables 



Exported Name of 
Entry Point 


Parameter 


Data Type of Parameter 


ALGOLGETREAL 


<structure> 


STRING 




<item name> 


STRING 




<variable name> 


REAL 


DBGETREAL 


<structure> 


DISPLAY 




<item name> 


DISPLAY 




<varjabie name> 


COM P-4 (COBOL) 

REAL (C0B0L74 or COBOL85) 


FORTRAN77GETREAL 


< structure > 


CHARACTER 




<ltem name> 


CHARACTER 




<variable name> 


REAL 



Structure 

The structure caa be either a data set or a databsuse. The following syntax diagrams 
show that if the name of the data set is not uotiique, you can use up to 12 qualifying 
parameters to uniquely identify the data set. A database name cannot be qualified. 



<structure> 



T— <data set qualified naine>- 
l—cdatabase name> 



<data set qualified name> 

— <naine>- 



/12\ 



OF — <name 
* /12\ 



. — <naine> 



The variables elements of the structure parameter are explained as follows: 
Element Explanation 

Identifies tlie data set that is to be accessed at mn time. 



<data set 
qualified name> 

<database 
name> 



Identifies the database for which the DMINTERPRETER library was 
compiled. 



continued 
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continued 

Element Explanation 

<name> Identifies the name of the data set or database. A name can consist of 

from 1 to 17 letters, digits, and-depending on the language-either 
underscores {_) or hyphens (-). The first character must be a letter. The 
last character must be either a letter or a digit. 

Item Name 

The following syntax diagrams show the valid combinations of characters that can be 
used to form an item name: 



<item name> 



•T— <underscore name>- 
'— <hyphen naine> 



— [ — L<i nteger>-L ] 

— ( -J— <i nteger>— L- ) 



<unclerscore name> 

— <letter>- 



/15\ -r-<letter>- 
[-<digit>- 



<underscore5 



C<1 etters 
<digit>- 



<hyphen name> 



0 etter>- 



/15\ — r-<letter>- 
[-<digit>— 
I— <hyphen>-' 



-r-<l etter>-- 
<digit>- 



The variable el^ents of an item name are explained as follows: 



Element 

< underscore 
name> 

< hyphen name> 



<int^er> 



Explanation 

A string of from 1 to 17 letters, digits, and underscores (_), starting with 
a letter and eriding with either a letter or a digit. 

A string of from 1 to 17 letters, digits,and hyphens (-), starting with a 
letter and ending with either a letter or a digit. 

A subscript for an OCCURS clause item. An Integer is a whole number 
(0123456789) that consists of from 1 to 12 digits and that has a 
maximum value of 549755813887. 



Variable Name 



Each language has a different way of identifying the variable that contains or evaluates 
to a real numeric value. Consult the appropriate language reference manual for more 
information on variables that can contain a real numeric value. 
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Note: For COBOL, the variable must he declared in the WORKING- 
STORAGE section of the program as a level 77 COMP'4 item. For 
COBOL74 and COBOL85, the variable must be declared as a level 77 
REAL item. 

Program Examples 

The following program fragments use GETREAL data transfer entry points to move 
nimieric values from the user work area to variables declared in the application program. 

ALGOL Program Fragment 

In the ALGOL example, the data set is EMI^ the item is £MP_NO, and the variable is 
EXPR_1. 

^Declaring local variables 

REAL 

EXPR_1; 
STRING 

DATA_SET_NAME, ITEM_NAME; 
BOOLEAN 
RSLT; 

%Assigning values to parameters 
DATA_SET_NAME:="EMP" ; 
%Declaring library entry point 
LIBRARY DMI; 

BOOLEAN PROCEDURE DBGETREAL(STRUCTURE, ITEM, VARIABLE) ; 
STRING STRUCTURE, ITEM; 
REAL VARIABLE; 

LIBRARY DMI (ACTUALNAME="ALGOLGETREAL") ; 
%Invoking entry point 
ITEM_NAME:="EMP_NO"; 

RSLT:=DBGETREAL(DATA_SET_NAME,ITEM_NAME,EXPR_1); 
IF RSLT 

THEN EXCEPTIONHANDLER; 



C0B0L74 or C0B0L85 Program Fragment 

In ttas example, the data set is EME^ the item is EMP-NO, and the variable is VAR-2. 
Since VAEt-2 is dedared as a REAL item and KBSULT is declared as a COMP item, this 
example can be either a COBOL74 or a COBOL85 program fragment. 
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Moving Numeric Values to Variables (cont.) 



Note: To make this a COBOL program fragment, declare the variable 

VAR-2 as a COMP-4 item and the variable RESULT as a COMP-2 

item. 

***Declaring variables 



01 DATA-SET-NAME 

01 ITEM-NAME 

01 VAR-2 

01 RESULT 



PIC X(17) VALUE IS "EMP". 
PIC X(17) VALUE IS SPACES. 
REAL. 

PIC 9(1) COMP VALUE IS 0. 



"Invoking entry point 



MOVE "EMP-NO" TO ITEM-NAME. 

CALL "DBGETREAL OF DMINTERPRETER" 

USING DATA-SET-NAME, ITEM-NAME, VAR-2 

GIVING RESULT. 



FORTRAN?? Program Fragment 

In this FORTRAN?? example, a value for DSNAME (the structure) is initialized at the 
beginning of the program; the value of ITMNAM (the item) is assigned in the body of the 
program. The variable is EXPRl. 

★★★Declaring library entry point 



LOGICAL FUNCTION DBGETR (STR, ITEM, VAR) 
CHARACTER STR, ITEM 
REAL VAR 

IN LIBRARY DMI (ACTUALNAME = "FORTRAN77GETREAL") 
END 

***Setting variables to initial values 

CHARACTER DSNAME *4 /"EMP"/, 
* ITMNAM *13 

REAL EXPRl 

★★★Declaring local variables 

LOGICAL RSLT 

★★★Invoking entry point 

ITMNAM = "EMP-NO" 

RSLT = DBGETR{DSNAME,ITMNAM, EXPRl) 
IF (RSLT) CALL EXCEPT 
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Moving Double-Precision Values to Variables 

Use the GETDOUBLE data transfer entry point to move a numeric value that exceeds 
the capacity of a real variable from a number, real, field, coimt, record-type, or population 
item to a program-declared variable. (See "Moving Numeric Values to Variables" in this 
section.) 

Passing Parameters 

The GETDOUBLE entry points have three required parameters: the name of the 
structure, the name of the item, and the name of the variable. 

Parameter Explanation 

<structure> Identifies the data set or the database in which the item is located. 

<item name> Identifies the data set item whose double-precision value is to be moved 

to the user-declared variable. 

<variable name> Identifies the user-declared variable by its name in the program. The 
variable must be able to contain a double-precision value. 

Note: If an exception occurs, the variable is set to HIGH-VALUE (all bits 
ON), and cm appropriate epcception is returned. Read Appendix B, 
"DMSn Exceptions and Errors, " for more information on exceptions. 
Consult the DMSII Technical Overview for an explanation of 
HIGH-VALUE. 

Table 4-5 gives the exported names of the entry points, as well as the parameters and 
the data type of each parameter. 



Table 4-5. Moving Double-Precision Values to Variables 



Exported Name of 
Entry Point 


Parameter 


Data Type of Parameter 


ALGOLGETDOUBLE 


<structure> 


STRING 




<item name> 


STRING 




<variable name> 


DOUBLE 


DBGETDOUBLE 


<structure> 


DISPLAY 




<ltem name> 


DISPLAY 




<variable name> 


COMP-5 (COBOL) 

DOUBLE (C0B0L74 or COBOL85) 


FORTRAN77GETDOUBLE 


<structure> 


CHARACTER 




<ltem name> 


CHARACTER 




<variabie name> 


DOUBLE PRECISION 
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Moving Double-Precision Values to Variables (cont.) 



structure 

The structure can be either a data set or a database. The following syntax diagrams 
show that if the name of the data set is not unique, you can use up to 12 qualifying 
parameters to uniquely identify the data set. A database name cannot be qualified. 



<structure> 



T— <data set qualified name>- 
L-<clatabase name> 



<data set qualified name> 



— <narae> 




The variable elements of the structure parameter are explained as follows: 



Element 



Explanation 



<data set 
qualified name> 



Identifies the data set that is to be accessed at run time. 



<datat)ase 
name> 



Identifies the database for which the DMINTERPRETER library was 
compiled. 



<name> 



Identifies the name of the data set or database. A name can consist of 
from 1 to 17 letters, digits, and-depending on the language-elther 
underscores (J or hyphens (-). The first character must be a letter. The 
last character must be either a letter or a digit. 



item Name 



The following syntax diagrams show the valid combinations of characters that can be 
used to form an item name: 



<item name> 



— r— <underscore name>- 
'— <hyphen naine> 



- [ — L-<integer>— L- ] — 




< underscore name> 



— <letter>- 




/15\ 



T— <1 etter: 
L<digit>- 
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Moving Double-Precision Values to Variables (cont.) 



<hyphen name> 



— <letter> 



It /15\ -i-<letter^-r-L 
h-«iigit> — 
«— <hyphen>— J 



T-<1 etter>-- 
l— <digit> — ' 



The variable elements of an item name are explained as follows: 



Element 



Explanation 



< underscore 
name> 



A string of from 1 to 17 letters, digits, and underscores (_), starting witli 
a letter and ending with either a letter or a digit. 



< hyphen name> 



A string of from 1 to 17 letters, digits, and hyphens (-), starting with a 
letter and ending with either a letter or a digit. 



<integer> 



A subscript for an OCCURS clause item. An int^er is a whole number 
(0123456789) that consists from of 1 to 12 digits and that has a 
maximum value of 549755813887. 



Variable Name 

Each language has a different way of identifying the entity that contains or evaluates to 
a real, double-precision nimieric value. Consult the appropriate language reference 
manual for more information on variables that can contain a real, double-precision 
numeric value. 

Note: For COBOL, the variable must be declared in the WORKING- 
STORAGE section as a level 77 COMP-S item. For COBOL74 and 
COBOL85, the variable must be declared as a level 77 DOUBLE item. 

Program Examples 

The following program fragments use the DBGETDOUBLE data transfer entry points to 
move double-precision numeric values from the user work area to variables declared in 
the application program. 

ALGOL Program Fragment 

In the ALGOL example, the structiire is initialized as EMP at the beginnjng of the 
program. The item name is is EMP^SSN. The variable is EXPB_2. 
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%Declaring local variables 

DOUBLE 
EXPR.2; 

string" 
data_setjame, item_name; 

BOOLEAN 
RSLT; 

%Assigning values to parameters 
DATA_SET_NAME:="EMP"; 
%Declanng library entry point 
LIBRARY DMI; 

BOOLEAN PROCEDURE DBGETDOUBLE(STRUCTURE,ITEM,VARIABLE) ; 
STRING STRUCTURE, ITEM; 
DOUBLE VARIABLE; 

LIBRARY DMI (ACTUALNAME="ALGOLGETDOUBLE") ; 



%Invoking entry point 



ITEM__NAME:="EMP__SSN"; 

RS LT: =DBGETDOUBLE (DATA_SET_NAME , ITEM_NAME . EXPR_2) ; 
IF RSLT 

THEN EXCEPTIONHANDLER; 



C0B0L74 or C0B0L85 Pr(^am Fragment 



In this example, the structure is BMP; the item is EMP-SSN. Since VAR-3 is declared as 
a DOUBLE item and RESULT is declared as a COMP item, this example can be either a 
COBOL74 or a COBOL85 program fragment. 

Note: To make this example a COBOL program fragment, declare the 

variable VAR-3 as a COMP-5 item and the variable RESULT as a 
COMP-2item. 



***Declaring variables 

01 DATA-SET-NAME 

01 ITEM-NAME 

01 VAR-3 

01 RESULT 



PIC X(17) VALUE IS "EMP". 
PIC X(17) VALUE IS SPACES < 
DOUBLE. 

PIC 9(1) COMP VALUE IS 0. 



***Invoking entry point 



MOVE "EMP-SSN" TO ITEM-NAME. 

CALL "DB6ETD0UBLE OF DMINTERPRETER" 

USING DATA-SET-NAME, ITEM-NAME, VAR-3 

GIVING RESULT. 
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FORTRAN?? Program Fragment 

In this FORTRAN?? example, EMP is the structure. The item name is EMP-SSN. The 
variable is EXPR2. 

***Declaring library entry point 

LOGICAL FUNCTION DBGETD (STR, ITEM, YAR) 
CHARACTER STR. ITEM 
DOUBLE PRECISION VAR 

IN LIBRARY DMI (ACTUALNAME = "F0RTRAN77GETD0UBLE") 
END 

***Setting variables to initial values 

CHARACTER DSNAME *4 /"EMP"/, 

* ITMNAM *13 

DOUBLE PRECISION EXPR2 

***Declaring local variables 

LOGICAL RSLT 

***Invoking entry point 

ITMNAM = "EMP-SSN" 

RSLT = DBGETD (DSNAME. ITMNAM, EXPR2) 

IF (RSLT) CALL EXCEPT 
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Retrieving Boolean Values 

Use the 6ETB00LEAN data transfer entry point to perform two functions: 

• Retrieve a Boolean value from either a Boolean item or a bit in a field item. 

• Set the value of a variable, as appropriate, to either TRUE or FALSE. 

Passing Parameters 

The GETBOOLEAN entry points have three required parameters: the name of the 
structure, the name of the item, and the name of the variable. 

Parameter Explanation 

<structure> Identifies the data set or the database in which the item is located. 

<item name> Identifies the data set item whose Boolean value is to be moved to the 

user-declared variable. 

< variable name> Identifies the user-declared variable by its name in the program. The 
variable must be able to contain a Boolean value (TRUE or FALSE). 

Note: If cm, exception occurs, the value of the variable is set to show a false 
condition. Consult Appendix B, ''DMSII Exceptions and Errors,'* for 
more information on exceptions. 

Table 4-6 gives the exported names of the entry points, as well as the parameters and 
the data type of each parameter. 

Table 4-6. Retrieving Boolean Values 



Exported Name of Entry R>int 


Parameter 


Data Type of 
Parameter 


ALGOLGETBOOLEAN 


<structure> 


STRING 




<item name> 


STRING 




<variable name> 


BOOLEAN 


DBGETBOOLEAN 


<structure> 


DISPLAY 




<item name> 


DISPLAY 




<variabie name> 


DISPLAY 


FORTRAN77GETBOOLEAN 


<structure> 


CHARACTER 




<item name> 


CHARACTER 




<variable name> 


LOGICAL 
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structure 



The structure can be either a data set or a database. The following syntax diagrsims 
show that if the name of the data set is not imique, you can use up to 12 qualifying 
parameters to uniquely identify the data set. A database name cannot be qualified. 



<structure> 

— |— «iata set qualified name>- 
L-<database name> 

<data set qualified name> 





< /12\ , 


1 




— »— OF — <nanie>— 






/12\ 1 






1 — l— . — <name>-J — ' 





The variable elements of the structure parameter are explained as follows: 
Element Explanation 

<data set Identifies the data set tliat is to be accessed at run time, 

qualified name> 

<database Identifies the database for which the DMINTERPRETER library was 

name> compiled. 

<name> Identifies the name of the data set or database. A name can consist from 

of 1 to 17 letters, digits, and-depending on the language, either 
underscores (_) or hyphens (-). The first character must be a letter. The 
last character must be either a letter or a digit. 

Item Name 



The following syntax diagrams show the valid combinations of characters that can be 
used to form an item name: 



<item name> 



— r-<underscore name>- 
<hypher» name> 



nteg 



nteger>— ] 



( — L-<integer>-^ ) - 



<un<ier$core name> 



detter:^ 



/15\ -|-<letter>- 
k-<digit>- 



L-<underscore5 



<letter>-J 
igit> — ' 
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<hyphen name> 



-<1 etter>- 




T- <letter>— 
'-<digit> — ' 



The variable elements of an item name are explained as foUows: 



Element 



Explanation 



< underscore 
name> 



A string of from 1 to 17 letters, digits, and underscores (_), starting with 
a letter and ending with either a letter or a digit. 



< hyphen name> 



A string of from 1 to 17 letters, digits, and hyphens (-), starting with a 
letter and ending with either a letter or a digit. 



<integer> 



A subscript for an OCCURS clause item. An integer is a whole number 
(0123456789) that consists of from 1 to 12 digits and that has a 
maximum value of 549755813887. 



Variable Name 

The Boolean parameter must evaluate to either the value TRUE or FALSE. Consult 
the appropriate language reference manual for more information on Boolean variables 
(ALGOL or COBOL) and logical variables (FORTEIAN77). 

Program Examples 

The following program fragments use the GETBOOLEAN entry points to move Boolean 
values from the user work area to variables declared in the application program. 

ALGOL Program Fragment 

In the ALGOL example, DATA_SET_NAME is initialized at the beginning of the 
program to the value of the structure EMP. The value for the item name, ITEM_NAME, 
is assigned as EMP_SEC_CLEAIt in the body of the program. The variable is EXPE_4. 
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%Declaring local variables 
STRING 

DATA_SET_NAME, ITEM_NAME; 
BOOLEAN 

EXPR_4, RSLT; 

%Assigning values to parameters 

DATA_SET_NAME:="EMP"; 

%Declaring library entry point 

LIBRARY DMI; 

BOOLEAN PROCEDURE DBGETBOOLEAN (STRUCTURE, ITEM, VARIABLE) ; 
STRING STRUCTURE, ITEM; 
BOOLEAN VARIABLE; 

LIBRARY DMI (ACTUALNAME="ALGOLGETBOOLEAN") ; 
%Invoking entry point 
ITEM_NAME : = " EMP_SEC_CLEAR" ; 

RSLT:=DBGETBOOLEAN{DATA_SET_NAME, ITEM_NAME,EXPR_4) ; 
IF RSLT 

THEN EXCEPTIONHANDLER; 



C0B0L74 or C0B0L85 Program: Fragment 

This example uses the structiare EMI? the item EMP-SEC-CLEAR, and the variable 
YAR-1. Becaiise the variable RESULT is declared as a COMP item, this example can be 
either a COBOL74 or a COBOL85 program. 

Note: To make this example a COBOL program fragment, declare the 
variable RESULT as a COMP-2 item. 

***Decl ari ng vari abl es 



01 DATA-SET-NAME 

01 ITEM-NAME 

01 VAR-1 

01 RESULT 



PIC X(17) VALUE IS "EMP". 
PIC X(17) VALUE IS SPACES, 
PIC X(10) VALUE IS SPACES. 
PIC 9(1) COMP VALUE IS 0. 



'Invoking entry point 



MOVE "EMP-SEC-CLEAR" TO ITEM-NAME. 
CALL "DBGETBOOLEAN OF DMINTERPRETER" 

USING DATA-SET-NAME, ITEM-NAME, VAR-1 

GIVING RESULT. 
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FORTRAN?? Pr(^am Fragment 

In this FORTRAN?? example, a value for DSNAME is initialized to EMP at the 
beginning of the program. The value of EMP-SEOCLEAR is assigned to ITMNAM in 
thebody of the program. The variable is EXPB4. 

***Declanng library entry point 

LOGICAL FUNCTION DBGETL (STR, ITEM, VAR) 
CHARACTER STR, ITEM 
LOGICAL VAR 

IN LIBRARY DMI (ACTUALNAME = "FORTRAN77GETLOGICAL") 

END . 

***Setting variables to initial values 

CHARACTER DSNAME *4 /"EMP"/. 

* ITMNAM *13 

LOGICAL EXPR4 

***Declaring local variables 

LOGICAL RSLT 

***Invoking entry point 

ITMNAM = "EMP-SEC-CLEAR" 

RSLT = DBGETL (DSNAME, ITMNAM, EXPR4) 

IF (RSLT) CALL EXCEPT 
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Placing Strings into Data Items 



Using a DBPUT data transfer entry point, you can move a string from a 
program-declared variable into a data item. The data item must be declared in the 
DASDL description as either an alpha item or a group item. 

Passing Parameters 

The data transfer entry points that move a string from a program-declared variable to a 
data item have three required parameters: the name of the structure, the name of the 
item, and the expression containing the string. 

Parameter Explanation 

<structure> Identifies either tiie data set (for an alpha item) or the database (for a 

global item) that is to be accessed at run time. 

<item name> Identifies the data set item to be modified. 

<expression> Identifies the user-declared variable by its name in the prc^ram. 

Note: If the string exceeds the defined length of the data item, DMSII 
returns an exception to the program. 

Table 4-7 gives the exported names of the entry points, as well as the parameters and 
the data type of each parameter. 



Table 4-7. Placing Strings into Data Items 



Exported Name of Entry Point 


Parameter 


Data Type of 
Parameter 


ALGOLPUTSTRING 


<structure> 


STRING 




<item name> 


STRING 




<expression> 


STRING 


DBPUTDISPLAY 


<structure> 


DISPLAY 




<item name> 


DISPLAY 




<variable> 


DISPLAY 


F0RTRAN77PUTCHARACTER 


<structure> 


CHARACTER 




<item name> 


CHARACTER 




<expresslon> 


CHARACTER 



Structure 



The structure can be either a data set or a database. The following syntax diagrams 
show that if the name of the data set is not unique, you can use up to 12 qualifying 
parameters to uniquely identify the data set. A database name cannot be qualified. 
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Placing Strings into Data Items (cont.) 



<structure> 



Cdata set qualified name>- 
database name> 



<data set qualified name> 

— <name>- 



Li!- 



/12\ 

OF — <name> 
— /12\ 



. <name> 



The variable elements of the structure parameter are explained as follows: 
Element Explanation 

identifies tiie data set tliat is to be accessed at run time. 



<data set 
qualified name> 

<datat}ase 
name> 

<name> 



Identifies the database for wliicti tiie OMINTERPRETER library was 
compiled. 

Identifies the name of the data set or database. A name can consist of 
from 1 to 17 letters, digits, and-depending on the language-either 
underscores (J or hyphens {-). The first character must be a letter. The 
last character must be either a letter or a digit. 



item Name 

The following syntax diagrams show the valid combixiations of characteris that can be 
used to form an item name: 



<item name> 



-J— <underscore name>- 
<hyphen name> 



— [ -J— <i ntegers^-l— ] 

— ( — ^i nteger>— L ) 



<under$core name> 



!letter>- 



/15\ — r-<letter> j- 

h-<digit> 

<underscore>— ' 



<letter> 



'— <digit 



<hyphen name> 



:letter>- 



/15\ -|-<1etter>- 
h-<digit>-- 
L- <hyphen>- 



-[— <letter>-j 
'-<digit> — • 
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Placing Strings into Data Items (cont.) 



The variable elements of a name are explained as follows: 



Element 



Explanation 



name> 



< underscore 



A string of from 1 to 17 letters, digits, and underscores (J, starting with 
a letter and ending with either a letter or a digit. 



< hyphen name> 



A string of from 1 to 17 letters, digits, and hyphens (-), starting with a 
letter and ending with either a letter or a digit. 



<integer> 



A subscript for an OCCURS clause item. An integer Is a whole number 
(0123456789) that consists of from 1 to 12 digits and that has a 
maximum value of 549755813887. 



Expression 



Bach lar^uage has a different \vay of identifying the expression that contains or 
evaluates to the string: 

• For ALGOL, it is a string expression. 

• For COBOL, it is a DISPLAY variable. 

• For FORTRAN??, it is a character expression. 

The syntax for the ALGOL string expression and for the FORTRAN?? character 
expression are shown in the following diagrams: 

<string expression > 

— <string primary^— i 1 1 



— ' — r— <character constants 1 — ' 1 

— <constant name> 

— <variable name> 

— <array element narae> 

— <substn*ng name> 

-<f unction reference>- — 
<character express! on>—' 

Consult the appropriate language reference manual for more information on expressions 
that can contain a string. 

Program Examples 

The following program fragments show how to use data transfer entry points to move 
data item values from string expressions declared in the application program to a DMSn 
user work area. 




■<stn*ng primary>- 



<character expression > 



/ / 
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Placing Strings into Data Items (cont.) 



ALGOL Program Fragment 

In the ALGOL example, the structure is EMI* the item name is EMP_FNAME, and 
EXPR_3 contains the string e:q)ression. Concatenation is used to create a string for the 
employee name being put into the database. 

%Declaring local variables 
STRING 

DATA_SET_NAME, ITEM^NAME, EXPR_3; 
BOOLEAN 
RSLT; 

%Assigning values to parameters 
DATA_SET_NAME:="EMP"; 
%Declaring library entry point 
LIBRARY DMI; 

BOOLEAN PROCEDURE DBPUTSTRING (STRUCTURE, ITEM, VARI AB LE) ; 
STRING STRUCTURE, ITEM, VARIABLE; 
LIBRARY DMI (ACTUALNAME="ALGOLPUTSTRING") ; 

%Invoking entry point 

ITEM_NAME : =" EMP_FNAME" ; 

RSLT:=DBPUTSTRING(DATA_SET_NAME,ITEM__NAME,EXPR_3 CAT "LINA"); 
IF RSLT 

THEN EXCEPTIONHANDLER; 



C0B0L74 or C0B0L85 Prc^m Fragment 

This example declares the structure as EMP, the item as EMP-FNAME, and the variable 
as VAR-1. Because the variable EESULT is declared as a COM? item, the example 
could be either a CX)BOL74 or a COBOLSd program fragment. 

iVbfe.* If the variable RESULT is declared as a COMP-2, tiiis example could 
he used as a COBOL program fragment 
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Placing Strings into Kanji Alpha Items (cont.) 



<$tructure> 



-p<data set qualified name>- 
'— <database name> 



<data set qualified name> 

— <name>- 



/12\ 



OF — <name> 
* /12\ 



. — <name> 



The variable elements of the structiire parameter are explained as follows: 



Element 

<data set 
qualified name> 

< database 
name> 

<name6' 



Explanation 

Identifies the data set tliat is to be accessed at mn time. 



Identifies tlie database for wfiich the DMINTERPRETER library was 
compiled. 

Identifies the name of the data set or database. A name can consist of 
from 1 to 17 letters, digits, and-depending on the language-either 
underscores (_) or hyphens (-). The first character must be a letter. The 
last character must be either a letter or a digit. 



Item Name 

The following syntax diagrams show the valid combinations of characters that can be 
used to form an item name: 



<item name> 



— I— <underscore name>- 
»-<hyphen name> 



nteger>-L ] 
nteger>— I— ) 



< underscore name> 



tletter>- 



IX 



/15\ -T-<1etter> r 

h-<digit> 

I— <underscore>-^ 



-p^letter>H 
•—cdigit* — I 



<hyphen name> 



cletter>- 



/15\ -,-<letter> 
[-<digit>- 
l— <hyphen3 



<1 etter>-4 
<digit> — ' 



L<d 
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Placing Strings into Kanji Alpha Items (cont.) 



The variable elements of an item name are e3q)lained as follows: 
Element Explanation 

<unclerscore A string of from 1 to 17 letters, digits, and underscores (_), starting with 

name> a letter and ending with either a letter or a digit. 

<hyphen name> A string of from 1 to 17 letters, digits, and hyphens (-), starting with a 
letter and ending with either a letter or a digit. 

<integer> A subscript for an OCCURS clause item. An int^er is a whole numt)er 

(0123456789) that consists of from 1 to 12 digits and that has a 
maximum value of 549755813887. 

Expression 

Each language has a different way of identifying the variable that contains or evaluates 
to the string: 

• For ALGOL, it is a string expression. 

• For COBOL74 and COBOL85, it is a variable. It can be defined as PIC X(2n) or PIC 
X(n) USAGE IS KANJI. 

• For FORTRAN??, it is a character expression. 

Note: Only COBOL74 and COBOL85 support Kanji characters; COBOL 
does not. 



<string expression > 

— <strir>g primary>- 



-C- CAT -r-<: 



string pnmary>- 



<character expression> 



/ / 



-<character constant>- 
— <constant name> 



«van*able nanie>- 



— <array element name) 
substring narae>- 



cf unction references— 
(character expression: 



Consult the appropriate language reference manual for more information on variables 
that can contain a Kanji string. 



Program Examples 

The following program &£^inents use PUTKANJI ^txy points to move data item values 
£rom string expressions declared in the application program to a DMSn user work area. 
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Placing Strings into Data Items (cont.) 



***Decl ari ng vari abl es 



01 
01 
01 
01 



DATA-SET-NAME 
ITEM-NAME 
VAR-1 
RESULT 



PIC X(17) VALUE IS "EMP". 
PIC X(17) VALUE IS SPACES, 
PIC X(10) VALUE IS SPACES, 
PIC 9(1) COMP VALUE IS 0. 



***Invoking entry point 



MOVE "EMP-FNAME" TO ITEM-NAME. 

CALL "DBPUTDISPLAY OF DMINTERPRETER" 

USING DATA-SET-NAME, ITEM-NAME, VAR-1 

GIVING RESULT. 



FORTRAN?? Program Fragment 

In this FORTRAN?? example, DSNAME contains the structijre; ITMNAM is the item 
name, EMP-FNAME; and EXPR3 contains the character expression. Concatenation is 
used to create a string for the employee name being put into the database. 

***Declaring library entry point 

LOGICAL FUNCTION DBPUTC (STR, ITEM, VAR) 
CHARACTER STR, ITEM, VAR 

IN LIBRARY DMI (ACTUALNAME = "F0RTRAN77PUTCHARACTER") 
END 

***Setting variables to initial values 

CHARACTER DSNAME *4 /"EMP"/, 

* ITMNAM *13 

* EXPR3 *22 

***Declaring local variables 

LOGICAL RSLT 

***Invoking entry point 

ITMNAM = "EMP-FNAME" 
EXPR3 = "CATHY" 

RSLT = DBPUTC (DSNAME, ITMNAM. EXPR3) 
IF (RSLT) CALL EXCEPT 
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Placing Strings into Kanji Alpha Items 



Using a PUTKANJI data transfer entry point, you can move a Kanji string into the user 
work area. The Kanji string must be in an alpha item that was dedared in the DASDL 
description as USAGE IS KANJI. 

Passing Parameters 

The PUTKANJI entry points have three required parameters: the name of the 
structiire, the name of the item, and the program-declared expression containing the 
string. 

Parameter Explanation 

<structure> Identifies either the data set or the database that is to be accessed at run 

time. 

<item name> Identifies the data set item to be modified. 

<expression> Identifies the user-declared variable by its name in the program. 

Note: If the string exceeds the defined length of the data item, DMSII 
returns an exception to the program. 

Table 4-8 gives the ei^orted names of the entry points, as well as the parameters and 
the data type of each parameter. 

Table 4-8. Placing Strings into Kanji Alpha Items 



Exported Name of Entry Point 


Parameter 


Data Type of 
Parameter 


ALGOLPUTKANJI 


<structure> 


STRING 




<item name> 


STRING 




<expression> 


STRING 


DBPUTKANJI 


<structure> 


DISPLAY 




<item name> 


DISPLAY 




<variable> 


DISPLAY or 
KANJI 


F0RTRAN77PUTKANJI 


<structure> 


CHARACTER 




<ltem name> 


CHARACTER 




<expresslon> 


CHARACTER 



Structure 



The structure can be either a data set or a database. The following syntax diagrams 
show that if the name of the data set is not imique, you can use up to 12 qualifying 
parameters to uniquely identify the data set. A database name cannot be qualified. 
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Placing Strings into Kanji Alpha Items (cont.) 



ALGOL Program Fragment 

In the ALGOL example, the structure is EMI^ the item is EMP_KNAME, and the 
variable is EXPR_3. Concatenation is used to create a string for the employee name 
before it is placed in the database. KANJI STKING is a string item containing Kanji 
characters that do not have a start-of-Kanji (SOIQ or end-of-Kanji (EOK) characters. 

%Declanng local variables 
STRING 

DATA_SET_NAME, ITEM_NAME, EXPR_3; 
BOOLEAN 
RSLT; 

%Assigning values to parameters 
DATA_SET_NAME:="EMP"; 
%Declaring library entry point 
LIBRARY DMI; 

BOOLEAN PROCEDURE DBPUTKANJI (STRUCTURE, ITEM,VARIABLE) ; 
STRING STRUCTURE, ITEM, VARIABLE; 
LIBRARY DMI (ACTUALNAME="ALGOLPUTKANJI") ; 

%Invoking entry point 

ITEM_NAME:="EMP_KNAME" ; 
EXPR_3:=KANJI_STRING; 

RSLT:=DBPUTKANJI(DATA_SET_NAME,ITEM_NAMEiEXPR_3 CAT KANI^STRING) ; 
IF RSLT 

THEN EXCEPTIONHANDLER; 



C0B0L74 or C0B0L85 Program Fragment 

In this example, the structure is EMI* the item is EMP-KNAME, and the variable is 
VAR-L The variable RESULT is declared as a COMP item. This program fragment 
could appear in either a COBOL74 or a COBOLSS program. 

Note: COBOL does not support Kanji characters. 
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Placing Strings into Kanji Alpiia Items (cont.) 



***Decl an" ng vari abl es 

01 DATA-SET-NAME 
01 ITEM-NAME 
01 VAR-1 

01 RESULT 

***Invoking entry point 



PIC X(17) VALUE IS "EMP". 
PIC X(17) VALUE IS SPACES. 
PIC X(10) USAGE IS KANJI. 

VALUE IS SPACES. 
PIC 9(1) COMP VALUE IS 0. 



MOVE "EMP-KNAME" TO ITEM-NAME. 
CALL "DBPUTKANJI OF DMINTERPRETER" 

USING DATA-SET-NAME, ITEM-NAME, VAR-1 

GIVING RESULT. 



F0RTRAN77 Program Fragment 

In this FORTRAN?? example, a value for DSNAME is initialized at the beginning of the 
program; the values of ITMNAM and EXPR3 are assigned in the body of the program. 
KNJSTR is a string item containing Kanji characters without the start-of-Kanji (SOK) or 
end-pf-Kanji (EOK) characters. 

***Declaring library entry point 

LOGICAL FUNCTION DBPUTK (STR, ITEM, VAR) 
CHARACTER STR, ITEM, VAR 

IN LIBRARY DMI (ACTUALNAME = "F0RTRAN77PUTKANvH") 
END 

***Setting variables to initial values 

CHARACTER DSNAME *4 /"EMP"/, 

* ITMNAM *13 , 

* EXPR3 *22 

***Declaring local variables 
LOGICAL RSLT 



***Invoking entry point 

ITMNAM = "EMP-KNAME" 
EXPR3 = KNJSTR 

RSLT = DBPUTK (DSNAME, ITMNAM, EXPR3) 
IF (RSLT) CALL EXCEPT 
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Placing Numeric Values into Data Items 



Use the PUTEEAL data transfer entzy point to place a numeric value from a number, 
real, or field item into the user work area. 

Passing Parameters 

The PUTREAL entry points have three required parameters: the name of the 
structure, the name of the item, and the name of the expression that contains the 
numeric value. 

Parameter Explanation 

<structure> Identifies tlie data set or the database that is to be accessed at run time. 

<item name> Identifies the data set item to be modified. 

<expression> Identifies the user-declared variable by its name in the prc^ram. 

Notes: 

• If the parameter for the real value produces an incorrect new 
value, DMSn returns an eocception to the program. 

• If the number of significant digits exceeds the capacity of the 
data item, use the ALGOLPUTDOUBLE, DBPUTDOUBLE, or 
FORTRAN77PUTDOUBLE entry point to place the real value 
into the item. 

Table 4-9 gives the exported names of the entry points, as well as the parameters and 
the data type of each parameter. 

Table 4-9. Placing Numeric Values into Data Items 



Exported Name of 
Entry Point 


Parameter 


Data Type of Parameter 


ALGOLPUTREAL 


<structure> 


STRING 




<item name> 


STRING 




<expression> 


REAL 


DBPUTREAL 


<structure> 


DISPLAY 




<item name> 


DISPLAY 




<varlable> 


COMP-4 (COBOL) 

REAL (C0B0L74 or COBOL85) 


F0RTRAN77PUTREAL 


<structure> 


CHARACTER 




<item name> 


CHARACTER 




<expression> 


REAL 
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Placing Numeric Values into Data Items (cont.) 



structure 

The structure can be either a data set or a database. The following syntax diagrams 
show that if the name of the data set is not unique, you can use up to 12 qualifying 
parameters to uniquely identify the. data set. A database name cannot be qualified. 



<$tructure> 



■T— <data set qualified names- 
'— <database naine> 



<data set qualified name> 





, /12\ , 


1 




— ^ OF — <name>-'— 






/12\ , 






l— ^ . — <name>— ' — ' 





The variable elements of the structure parameter are explained as follows: 



Element 

<data set 
qualified name> 

<database 
name> 

<name> 



Explanation 

Identifies the data set that is to be accessed at run time. 



Identifies the database for which the DMINTERPRETER library was 
compiled. 

Identifies the name of the data set or database. A name can consist of 
from 1 to 17 letters, digits, and-depending on the language-either 
underscores (_) or hyphens (-). The first character must be a letter. The 
last character must be either a letter or a digit. 



Item Name 



The following syntax diagrams show the valid combinations of characters that can be 
used to form an item name: 



<item name> 



-p<underscore name>- 
<hyphen name> 



- [ —L^i nteger>-L- ] 

- ( — l--<i n teger>-J— ) 



< underscore name> 



sletter>- 



/15\ -i-cletter>- 
H-<digit>- 



L-<underscore5 



<letters 



L<digit 



4-42 



8600 0155-000 



Placing Numeric Values into Data Items (cont.) 



<hyphen name> 



— <1 etter>- 





/15\ 



— [— <1 etter>— r 
^-<d^g^t> — 
<hyphen>— ' 



The variable elements of an item name are explained as follows: 



Element 



Explanation 



< underscore 



A string of from 1 to 17 letters, digits, and underscores (J, starting with 
a letter and ending with either a letter or a digit. 



name> 



< hyphen name> 



A string of from 1 to 17 letters, digits, and hyphens (-), starting with a 
letter and ending with either a letter or a digit. 



<int^er> 



A subscript for an OCCURS clause item. An int^er is a whole number 
(0123456789) that consists of from 1 to 12 digits and that has a 
maximum value of 549755813887. 



Expression 



Each language has a different way of identifying the entity that contains or evaluates to a 
real numeric value: 

• For ALGOL, it is an arithmetic expression. 

• For COBOL, the variable must be declared in the WORKING-STORAGE section of 
the program as a level 77 COMP-4 item. 

• For COBOL74 and COBOL85, the variable must be declared in the 
WORKING-STORAGE section of the program as a level 77 REAL item. 

• For FORTRAN77, it is an arithmetic expression. 
<arithmetic expression > in ALGOL 

— r-<siinple arithmetic expression> 1 1 

'— <conch'tional arithmetic expression>-J 

or'rthmetic expression> in F0RTRAN77 
p«— <arithmetic operation>-i 




Consult the appropriate language reference manual for more information on variables 
that can contain a real ntmieric value. 

Program Examples 

The followii^ program fragments use PUTREAL entry points to move ntimeric values 
from variables declared in the application program to the user work area. 
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Placing Numeric Values into Data Items (cont.) 



ALGOL Prc^ram Fragment 

In the ALGOL example, a value for DATA SET NAME (the structure) is initialized at 
the beginmng of the program; the value for ITEM NAME (item name) and the value for 
EXPB_1 (the variable) are assigned in the body of the program. 

%Declanng local variables 

REAL 

EXPR_1; 
STRING 

DATA_SET_NAME, ITEM_NAME; 
BOOLEAN 
RSLT; 

%Assigning values to parameters 
DATA_SET_NAME:="EMP"; 
%Declaring library entry point 
LIBRARY DMI; 

BOOLEAN PROCEDURE DBPUTREAL(STRUCTURE, ITEM, VARIABLE) ; 
STRING STRUCTURE, ITEM; 
REAL VARIABLE; 

LIBRARY DMI (ACTUALNAME="ALGOLPUTREAL") ; 

%Invoking entry point 

ITEM_NAME:="EMP_NO"; 
EXPR_1:="11"; 

RSLT:=DBPUTREAL(DATA_SET_NAME,ITEM_NAME,EXPR 1) ; 
IF RSLT 

THEN EXCEPTIONHANDLER; 



C0B0L74 or C0B0L85 Program Fragment 

This example shows either a CX)60L74 or a COBOL85 program fragment. The variable 
VAR-2 is declared as a REAL item and EESULT as a COMP itemThe structure is EMP 
and the item is EMP-NO. 

Note: If VAR-2 is declared as a COMP-4 item and RESULT is declared as 
a COMP'2 item, this example could be used in a COBOL program. 
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Placing Numeric Values into Data Items (cont.) 



***Decl an* ng van* abl es 



01 DATA-SET-NAME 

01 ITEM-NAME 

01 VAR-2 

01 RESULT 



PIC X(17) VALUE IS "EMP". 
PIC X{17) VALUE IS SPACES. 
REAL. 



PIC 9(1) COMP VALUE IS 0. 



★★★Invoking entry point 

MOVE "EMP-NO" TO ITEM-NAME. 

MOVE 11 TO VAR-2. 

CALL "DBPUTREAL OF DMINTERPRETER" 

USING DATA-SET-NAME. ITEM-NAME, VAR-2 

GIVING RESULT. 



FORTRAN?? Pri^am Fragment 

In this FORTRAN?? example, a value for DSNAME is initialized at the beginning of the 
program; the value of ITMNAM and the value of EXPRl are assigned in the body of the 
program. 

***Declaring library entry point 

LOGICAL FUNCTION DBPUTR (STR, ITEM. VAR) 
CHARACTER STR, ITEM 
REAL VAR 

IN LIBRARY DMI (ACTUALNAME = "FORTRAN? 7 PUTREAL") 
END 



REAL EXPRl 

***Declaring local variables 

LOGICAL RSLT 

***Invok1ng entry point 

ITMNAM = "EMP-NO" 
EXPRl = 11 

RSLT = DBPUTR(DSNAME, ITMNAM, EXPRl) 
IF (RSLT) CALL EXCEPT 



***Setting variables to initial values 



CHARACTER DSNAME 
* ITMNAM 



★4 
*13 



/"EMP"/, 
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Placing Double-Precision Values into Data Items 

Use the PUTDOUBLE data transfer entry points to move a double-precision numeric 
value from a program-declared variable to a data item. The data item must be defined in 
the DASDL description as a number, real, or field item. (See "Placing Numeric Values 
into Data Items'' in this section.) 

Passing Parameters 

The PUTDOUBLE entry points have three required parameters: the name of the 
structure, the name of the item, and the name of the e:q)ression that contains the 
nimieric value. 

Parameter Explanation 

<structure> Identifies the data set or the database that is to be accessed at run time. 

<item name> Identifies the data set item to be modified. 

<expression> Identifies the user-declared variable by its name in the program. 

Note: If the parameter for the real value produces an incorrect new value, 
DMSn returns an exception to the pmgram. 

Table 4-10 gives the exported names of the entry points, as well as the parameters and 
the data type of each parameter. 

Table 4-10. Placing Double-Precision Values into Data Items 



Exported Name of 
Entry Point 


Parameter 


Data Type of Parameter 


ALGOLPUTDOUBLE 


<structure> 


STRING 




<item name> 


STRING 




<expression> 


DOUBLE 


DBPUTDOUBLE 


<structure> 


DISPLAY 




<item name> 


DISPLAY 




<variabie> 


COMP-5 (COBOL) 

DOUBLE (C0B0L74 or C0B0L85) 


FORTRAN77PUTDOUBLE 


<structure> 


CHARACTER 




<item name> 


CHARACTER 




<expression> 


DOUBLE 
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Placing Double-Precision Values into Data Items (cont.) 



structure 

The structure can be either a data set or a database. The following syntax diagrams 
show that if the name of the data set is not unique, you can use up to 12 qualifying 
parameters to imiquely identify the data set. A database name cannot be qualified. 



<structure> 



J- <clata set qualified name>- 
L-<database name> 



<data set qualified name> 

— <name>- 



/12\ 

OF — <name> 
— /12\ 



. — <name>- 



The variable elements of the structure parameter are e:q>lained as foUows: 



Element 

<data set 
qualified name> 

<database 
name> 

<name> 



Explanation 

Identifies the data set that is to be accessed at run time. 



Identifies the database for which the DI^INTERPRETER library was 
compiled. 

Identifies the name of the data set or datat)ase. A name can consist of 
from 1 to 17 letters, digits, and-depending on the language-either 
underscores (_) or hyphens (-). The first character must be a letter. The 
last character must be either a letter or a digit. 



Item Name 

The following syntax diagrams show the valid combinations of characters that can be 
\ised to form an item name: 



<item name> 



— p-<underscore name>- 
L- <hyphen name> 



- [ — L^integer>-J— ] 

- ( — L-<i nteger>-L- ) 



<under5core name> 



sletter>- 



/15\ -p-<letter>- 
h-<digit>- 



»— <underscore: 



etter>-j 
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<hyphen name> 



:letter>- 



/15\ -p<letter^ 
h-<digit>— 
'— <hyphen>- 



<1 etters 



'— <digit 



The variable elements of an item name are explained as follows: 
Oement Explanation 

< underscore A string of from 1 to 17 letters, digits, and underscores (_), starting with 

name> a letter and ending with either a letter or a digit. 

< hyphen name> A string of from 1 to 17 letters, digits, and hyphens (-), starting with a 
letter and ending with either a letter or a digit. 

<integer> A subscript for an OCCURS clause item. An int^er is a whole number 

(0123456789) that consists of from 1 to 12 digits and that has a 
maximum value of 549755813887. 

Expression 

Each language has a different way of identifying the entity that contains or evaluates to a 
real, double-precision mmieric value: 

• For ALGOL, it is an arithmetic expression. 

• For COBOL, the variable must be declared in the WORKING-STOKAGE section of 
the program as a level 77 COMP-5 item. 

• For COBOL74 and COBOL85, the variable must be declared in the 
WORKING-STORAGE section of the program as a level 77 DOUBLE item. 

• For FORTRAN77, it is an arithmetic expression. 



<arithmetic expression > in ALGOL 

<siinple arithmetic express! on>- 



conditional arithmetic expression 



orithmetic expression > in F0RTRAN77 

r«— <arithmetic operation>— i 
-l-<operand> L 



_ + _ 



Consult the appropriate language reference manual for more information on variables 
that can contain a real, double-precision, numeric value. 



Program Examples 

The foUowii^ program fragments use PUTDOUBLE entry points to move numeric 
values firom variables declared in the application program to the user work area. 
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Placing Double-Precision Values into Data Items (cont.) 



ALGOL Pr<^am Fragment 

In the ALGOL example, the structiu'e is EMI^ the item is EMP-SSN, and the arithmetic 
expression is (EXPR_2 - 11). 

%Declaring local variables 

DOUBLE 

EXPR_2; 
STRING 

DATA_SET_NAME, ITEM_NAME; 
BOOLEAN 
RSLT; 

%Assigning values to parameters 
DATA__SET_NAME:="EMP" ; 
%Declaring library entry point 
LIBRARY DMI; 

BOOLEAN PROCEDURE DBPUTDOUBLE (STRUCTURE, ITEM, VARIABLE) ; 
STRING STRUCTURE, ITEM; 
DOUBLE VARIABLE; 

LIBRARY DMI (ACTUALNAME="ALGOLPUTDOUBLE") ; 

%Invoking entry point 

ITEM_NAME:="EMP_SSN"; 
EXPR~2:=" 5732309 11"; 

RSLT:=DBPUTD0UBLE(DATA_SET_NAME,ITEM_NAME,EXPR_2 -11); 
IF RSLT 

THEN EXCEPTIONHANDLER; 



C0B0L74 or C0B0L85 Program Fragment 

Because VAR-3 is declared as a DOUBLE item and HESULT is declared as a COMP 
item, this program fragment can be used in either a COBOL74 or a COBOL85 program. 

Note: By declaring the variable VARS a COMP-5 item and RESULT as a 
COMP'2 item, this example become a COBOL program fragment 
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Placing Double-Precision Values into Data Items (cont.) 



***Dec1 an' ng van' abl es 

01 DATA-SET-NAME 
01 ITEM-NAME 
01 VAR-3 
01 RESULT 

★★★Invoking entry point 



PIC X(17) VALUE IS "EMP". 
PIC X(17) VALUE IS SPACES. 
DOUBLE. 

PIC 9(1) COMP VALUE IS 0. 



MOVE "EMP-SSN" TO ITEM-NAME. 

MOVE 573230911 TO VAR-3. 

CALL "DBPUTDOUBLE OF DMINTERPRETER" 

USING DATA-SET-NAME, ITEM-NAME, VAR-3 

GIVING RESULT. 



FORTRAN?? Program Fragment 

In this FORTRAN?? example, a value for DSNAME is initialized at the beginning of the 
program; the value of ITMNAM and the value of EXPR2 are assigned in the body of the 
program. The arithmetic expression is (EXPR2 - 11). 

***Declaring library entry point 

LOGICAL FUNCTION DBPUTD (STR, ITEM, VAR) 
CHARACTER STR. ITEM 
DOUBLE PRECISION VAR 

IN LIBRARY DMI (ACTUALNAME = "FORTRAN77PUTDOUBLE") 
END 

***Setting variables to initial values 

CHARACTER DSNAME *4 /"EMP"/, 

* ITMNAM *13 

DOUBLE PRECISION EXPR2 



***Declaring local variables 

LOGICAL RSLT 

***Invoking entry point 

ITMNAM = "EMP-SSN" 
EXPR2 = 573230911 

RSLT = DBPUTD (DSNAME. ITMNAM, EXPR2 - 11 ) 
IF (RSLT) CALL EXCEPT 
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Setting Data Items to Boolean Values 



You can use a DBPUT data transfer entry point to place a Boolean value into a 
BOOLEAN item. 



Passing Parameters 

The data transfer entry points that place Boolean values into Boolean items have 
three required parameters: the name of the structure, the name of the iteni, and the 
expression containing the Boolean value. 

Parameter Explanation 

<structure> Identifies tlie data set or the datat)ase tiiat is to be accessed at run time. 

< item name> Identifies the data set item to be modified. 

<expression> identifies the user-declared variable by its name in the program. In all 

cases, the expression must evaluate to either TRUE or FALSE. 

Table 4-11 gives the exported names of the entry points, as weU as the parameters and 
the data type of each parameter. 

Table 4-11. Setting Data Items to Boolean Values 



Exported Name of Entry Point 


Parameter 


Data Type of 
Parameter 


ALGOLPUTBOOLEAN 


<structure> 


STRING 




<item name> 


STRING 




<expression> 


BOOLEAN 


DBPUTBOOLEAN 


<structure> 


DISPLAY 




<item name> 


DISPLAY 




<variable> 


DISPLAY 


F0RTRAN77PUTL0GICAL 


-<structure> 


CHARACTER 




<item name> 


CHARACTER 




<expression> 


LOGICAL 



Structure 



The structure can be either a data set or a database. The following syntax diagrams 
show that if tiie name of the data set is not imique, you can use up to 12 qualifying 
parameters to tmiquely identify the data set. A database name cannot be qualified. 
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Setting Data Items to Boolean Values (cont.) 



<structure> 



— r-<data set qualified name>- 
l— <database name> 



<data set qualified name> 

— <name>- 



/12\ 



OF — <name>- 

— /12\ 1 

. — <name>— ' 



The variable elements of the structure parameter are explained as follows: 
Element Explanation 



<clata set 
qualified name> 

<database 
name> 

<name> 



Identifies the data set that is to be accessed at run time. 

Identifies the datatiase for which the DI\/IINTERPRETER library was 
compiled. 

Identifies the name of the data set or database. A name can consist of 
from 1 to 17 letteiB, digits, and-depending on the language-either 
underscores (_) or hyphens (-). The fiist character must be a letter. The 
last character must be either a letter or a digit. 



Item Name 

The following syntax diagrams show the valid combinations of characters that can be 
used to form an item name: 



<item name> 

:undersco 
shyphen name>- 



— r~'^""<^^''score name>- 



— [ — ^i nteger>-'— ] 

— ( — l-^integer>-L- ) 



<underscore name> 



sletter>- 



It 



/15\ -r-<letter>- 
k<digit>- 



'-<underscore>-' 



-r-<l etter>-H 
'-<digit> — ' 



<hyphen name> 



:letter>- 



Lr 



/15\ — [— <letter5^ 
p:digit> — 
■-^hyphens-J 



etter>-| 
igit> — ' 



igit 
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Setting Data Items to Boolean Values (cont.) 



The variable elements of an item name are e^lained as follows; 
Element Explanation 

<unclerscore A string of from 1 to 17 letters, digits, and underscores (J, starting with 

name> a letter and ending with either a letter or a digit. 

<hyphen name> A string of from 1 to 17 letters, digits, and hyphens (-), starting with a 
letter and ending with either a letter or a digit. 

<integer> A subscript for an OCCURS clause item. An integer is a whole number 

(0123456789) that consists of from 1 to 12 digits and that has a 
maximum value of 549755813887. 

Expression 

The Boolean parameter must evaluate to either the value TRUE or FALSE: 

• For ALGOL, it is a Boolean expression. 

• For COBOL, it is a DISPLAY variable that holds the Boolean value. 

• For FORTRAN??, it is a logical expression and must evaluate to either .TRUE or 
.FALSE. (Note that the period preceding the kejrword is required.) 



<Boolean expression> 

-<simple Boolean express! on>- 



C^simpie Dooiean expression-* r- 
<conditional Boolean expressions— J 



<logical expression > 



logical operands 



r 



— .AND. — r— <logical operand>--^ 
.OR. — 
.NEQ. - 
1- .EQ. —I 



Consult the appropriate language reference manual for more information on Boolean 
expressions. 



Program Examples 



The foUovdng program fragments use data transfer entry points to move a value of 
FALSE from a Boolean item in the prc^ram to a user work area. 



ALGOL Program Fragment 



In the ALGOL example, DATA_SET_NAME is the structure, ITEM_NAME is the item, 
and EXPR_4 contains the Boolean expression. 
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Setting Data Items to Boolean Values (cont.) 



%Declaring local variables 
STRING 

DATA_SETJAME. ITEM^NAME; 
BOOLEAN 

EXPR_4. RSLT; 

%Assl9n1n9 values to parameters 

DATA_SET_NAME;="EMP"; 

%Declaring library entry point 

LIBRARY DMI; 

BOOLEAN PROCEDURE DBPUTBOOLEAN (STRUCTURE, ITEM, VARIABLE) ; 
STRING STRUCTURE, ITEM; 
BOOLEAN VARIABLE; 

LIBRARY DMI (ACTUALNAME="ALGOLPUTBOOLEAN") ; 



%Invoking entry point 

ITEM_NAME: ="EMP_SEC_CLEAR" ; 
EXPR_4:=TRUE; 

RS LT : =DBPUTB0OLEAN (DATA_SET_NAME , ITEM_NAME , EXPR_4) ; 
IF RSLT 

THEN EXCEPTIONHANDLER; 



C0B0L74 or C0B0L85 Program Fragment 



In this example, EMP is the structure, EMP-SEC-CLEAR is the item, and VAK-1 is the 
variable. The variable RESULT is declared as a COMP item, making this example a 
COBOL74 or a COBOL85 program fragment. 

Note: To make this a COBOL program fragment, declare the variable 
RESULT as a COMP-2 item. 

***Decl aring variabl es 



01 DATA-SET-NAME 

01 ITEM-NAME 

01 VAR-1 

01 RESULT 



PIC X(17) VALUE IS "EMP". 
PIC X(17) VALUE IS SPACES, 
PIC X(10) VALUE IS SPACES, 
PIC 9(1) COMP VALUE IS 0. 



***Invoking entry point 



MOVE "EMP-SEC-CLEAR" TO ITEM-NAME. 

MOVE "TRUE" TO VAR-1. 

CALL "DBPUTBOOLEAN OF DM INTERPRETER" 

USING DATA-SET-NAME, ITEM-NAME, VAR-1 

GIVING RESULT. 
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Setting Data Items to Boolean Values (cont.) 



FORTRAN?? Program Fragment 

In this FORTRAN?? example, a value for DSNAME is initialized at the beginning of the 
program; the value of ITMNAM and the value of EXPR4 are assigned in the body of the 
program. 

***Declaring library entry point 

LOGICAL FUNCTION DBPUTL (STR, ITEM, VAR) 
CHARACTER STR, ITEM 

LOGICAL VAR 

IN LIBRARY DMI (ACTUALNAME = "FORTRAN77PUTL0GICAL") 
END 

***Setting variables to initial values 

CHARACTER DSNAME *4 /"EMP"/, 
* ITMNAM *13 

LOGICAL EXPR4 

***Declanng local variables 

LOGICAL RSLT 

***Invoking entry point 

ITMNAM = "EMP-SEC-CLEAR" 
EXPR4 = .TRUE 

RSLT = DBPUTL(DSNAME, ITMNAM, EXPR4) 
IF (RSLT) CALL EXCEPT 
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Setting Data Items to Null Values 

Use PUTNULL entiy points to set a data item to its null value. The data item cannot 
be defined in the DASDL description as either a lo^cal, a count, a record-type, or a 
population item. 

Passing Parameters 

PUTNULL entry points have two required parameters: the name of the structure and 
the name of the item. 

Parameter Explanation 

<structure> Identifies the data set or the database that is to be accessed at run time. 

<item name> Identifies the data set item to be modified. 

Table 4-12 gives the exported names of the entry points, as well as the parameters and 
the data type of each parameter. 



Table 4-12. Setting Data Items to Null Values 



Exported Name of Entry Point 


Parameter 


Data Type of 
Parameter 


ALGOLPUTNULL 


<structure> 


STRING 




<item name> 


STRING 


DBPUTNULL 


<structure> 


DISPLAY 




<item name> 


DISPLAY 


F0RTRAN77PUTNULL 


<structure> 


CHARACTER 




<item name> 


CHARACTER 



Structure 

The structure can be either a data set or a database. The following £;yntax diagrams 
show that if the name d[ the data set is not unique, you can use up to 12 qualifying 
parameters to uniquely identify the data set. A database name cannot be qualified. 

<structure> 

— r-<clata set qualified naine>-| — | 

L-<database naine> ' 
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Setting Data Items to Null Values (cont.) 



<data set qualified name> 

— <name>- 



/12\ 

OF — <name> 
— /12\ 
. — <name> 



The variable elements of the structure parameter are explained as follows: 



Element 

<data set 
qualified riame> 

<database 
name> 

<name> 



Explanation 

Identifies the data set that Is to be accessed at run time. 

Identifies the database for which the DMINTERPRETER library was 
compiled. 

Identifies the name of the data set or database. A name can consist of 
from 1 to 17 letters, digits, and-depending on the language-either 
underscores {_) or hyphens (-). The first character must be a letter. The 
last character must be either a letter or a digit. 



item Name 

The following syntax diagrams show the valid combinations of characters that can be 
used to form an item name: 



<item name> 



j-<underscore name>- 
1— <hyphen name> — 



[ — nteger>— L- ] 
nteger>-L- ) 



< underscore name> 



si etter>- 



/15\ -p<letter>- 
[-<digit>- 



'— <underscore5 



-r-<l fitters 
'— <dig^t>■ 



<i1yphen name> 



cletter>- 



/15\ -T-<letter>- 
k<digit>- 
'-<hyphen>- 



-i-<letter: 
«-<digi 
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Setting Data Items to Null Values (cont.) 



The variable elements of an item name are explained as follows: 



Element 



Explanation 



<unclerscore 
name> 



A string of from 1 to 17 letters, digits, and underscores (_), starting with 
a letter and ending with either a letter or a digit. 



< hyphen name> 



A string of from 1 to 17 letters, digits, and hyphens (-), starting with a 
letter and ending with either a letter or a digit. 



<lnteger> 



A subscript for an OCCURS clause item. An integer is a whole number 
(0123456789) that consists of from 1 to 12 digits and that has a 
maximum value of 549755813887. 



Program Examples 

The following program fragments use the PUTNULL entry points to set data items to 
their null values. The structure is EME 

ALGOL Program Fragment 

In the ALGOL example, the data item value is EMP_SALARY. 
%Declaring local variables 
STRING 

DATA_SET_NAME, ITEM__NAME; 
BOOLEAN 
RSLT; 

%Assigning values to parameters 
DATA_SET_NAME:="EMP"; 
%Declaring library entry point 
LIBRARY DMI; 

BOOLEAN PROCEDURE DBPUTNULL (STRUCTURE, ITEM) ; 
STRING STRUCTURE, ITEM; 
LIBRARY DMI (ACTUALNAME^-'ALGOLPUTNULL") ; 

%Invoking entry point 

ITEM_NAME : = " EMP_SALARY" ; 

RS LT : =DBPUTBOOLEAN (DATA_SET_NAME , ITEM^NAME) ; 
IF RSLT 

THEN EXCEPTIONHANDLER; 
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Setting Data Items to Null Values (cont.) 



C0B0L74 or C0B0L85 Program Fragment 

In the example, the data item value is EMP-SALAKY. Because the variable RESULT is 
declared as a COMP item, this fragment can be used in a COBOL74 or a COBOL85 
program. 

Note: To make this example a COBOL program fragment, declare 
RESULT as a COMP-2 item. 

***Decl ari ng vari abl es 

01 DATA-SET-NAME PIC X(17) VALUE IS "EMP". 

01 ITEM-NAME PIC X(17) VALUE IS SPACES. 

01 RESULT PIC 9(1) COMP VALUE IS 0. 

★★★Invoking entry point 

MOVE "EMP-SALARY" TO ITEM-NAME. 
CALL "DBPUTNULL OF DMINTERPRETER" 

USING DATA-SET-NAME, ITEM-NAME 

GIVING RESULT. 



FORTRAN?? Pr(^am Fragment 

In the FORTRAN?? example, the data item value is EMP-SALARY. 
***Declaring library entry point 

LOGICAL FUNCTION DBPUTN (STR, ITEM) 
CHARACTER STR, ITEM 

IN LIBRARY DMI (ACTUALNAME = "F0RTRAN77PUTNULL") 
END 

***Setting variables to initial values 

CHARACTER DSNAME *4 /"EMP"/, 
* ITMNAM *13 

***Declaring local variables 

LOGICAL RSLT 

***Involcing entry point 

ITMNAM = "EMP-SALARY" 

RSLT = DBPUTN (DSNAME, ITMNAM) 

IF (RSLT) CALL EXCEPT 
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Constructing Data Transfers during Program Execution 

You can cjyiiamically construct DBGET and DBPUT operations during program 
execution through a DATA data transfer entry point. 

Passing Parameters 

The DATA entry points have two required parameters: the data request parameter and 
the data parameter. 

Parameter Explanation 

<clata request> Specifies the type of operation (DBGET or DBPUT), the data type of the 

item to be transferred, and the structure and item involved in the 
operation. 

<data> For DBPUT operations, specifies the actual data that is moved to the 

user work area from the prc^ram. 

For DBGET operations, specifies the actual data that is moved from the 
user work area to the program. 

Table 4-13 gives the exported names of the entry points, as well as the parameters and 
the data type of each parameter. 



Table 4-13. Constructing Transfers during Program Execution 



Exported Name of Entry Point 


Parameter 


Data Type of 
Parameter 


ALGOLDATA 


<data request> 


STRING 




<data> 


STRING 


DBDATA 


<data request> 


DISPLAY 




<data> 


DISPLAY 


FORTRAN77DATA 


<data request> 


CHARACTER 




<data> 


CHARACTER 



There are two syntaxes for the data request parameter: one for ALGOL and COBOL, 
and one for FORTRAN??. All languages use the same syntax for the data parameter. 

ALGOL and COBOL <data request> 



- PUT ~1 U 



6ET 



BOOLEAN 
REAL — 



- STRING — I 
I- KANJI - 
L- PUT — NULL 



:structure> — <i tan>- 
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Constructing Data Transfers during Program Execution (cont.) 



FORTRAN?? <data request> 



LOGICAL — 

REAL 

CHARACTER 

KAN J I 

- PUT — NULL 




Element 

GET <data type> 

<structure> 

<item> 



PUT <data 1ype> 

<structure> 

<item> 



-<structure> — <i tem>- 



Explanation 

For ALGOL, COBOL, C0B0L74, and COBOL85 programs, moves a data 
value of type Boolean, real, string, or Kanji to a variable declared In the 
program. The user work area Is searched for the specified structure and 
data set item. The structure can be either a data set or a database. 

For FORTRAN?? programs, moves a data value of type logical, real, 
character, or Kanji to a variable declared in the program. The user work 
area is searched for the specified structure and data set item. The 
structure can be either a data set or a database. 

For ALGOL, COBOL, C0B0L?4, and COBOL85 programs, moves a data 
value of type Boolean, real, string, Kanji, or null from a variable declared 
in the program to the work area. During a store operation, the value will 
be stored in the specified structure and data set item. The structure can ^ 
be either a data set or a database. 

For FORTRAN??, moves a data value of type logical, real, character, 
Kanji, or null from a variable declared in the program to the specified 
data set item in the structure. The structure can be either a data set or a 
database. 



<data> 



— [— <Boolean variable>-r 
|— <real variable> 



I— <stn'ng variable; 
Element Explanation 

<data> A Boolean, real, or string variable declared in the prc^ram. The variable 

must meet the appropriate language requirements for a variable of that 
type. Consult the appropriate language reference manual. 
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Program Examples 

The following program fragments use DATA entry points to to set data items to their 
null values. 



ALGOL Program Fragment 

%beclanng local variables 
STRING 

DATA^REQUEST, DATA_BUFFER; 
BOOLEAN 
RSLT; 

^Assigning values to parameters 

%Values are assigned to the declared variables within the body of the 
%program, 

%Declaring library entry point 
LIBRARY DMI; 

BOOLEAN PROCEDURE DBDATA (REQUEST, DATA) ; 
STRING REQUEST, DATA; 
LIBRARY DMI (ACTUALNAME="ALGOLDATA") ; 

%Invoking entry point 

DATA_REQUEST:="PUT REAL EMP EMP-DATE-HIRED"; 

DATA_BUFFER:="811223"; 

RSLT : ^DBDATA (DATA_REQUEST. DATA__BUFFER) ; 

IF RSLT 

THEN EXCEPTIONHANDLER; 



C0B0L74 or C0B0L85 Program Fragment 

Note: . The variable RESULT is declared as a COMP item, making this 

example either a COBOL74 or a COBOL85 program fragment If it 
had been declared as COMP'2 item, the fragment could be used in a 
COBOL program. 
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Constructing Data Transfers during Program Execution (cont.) 



Declaring variables 



01 DATA-REQUEST 
01 DATA-BUFFER 
01 RESULT 



PIC X(40) VALUE IS SPACES. 
PIC X(10) VALUE IS SPACES. 
PIC 9(1) COMP-2 VALUE IS 0. 



***Invoking entry point 

MOVE "GET REAL EMP EMP-NO" TO DATA_REQUEST. 
CALL "DBDATA OF DMINTERPRETER" 

USING DATA-REQUEST, DATA-BUFFER 

GIVING RESULT. 



FORTRAN?? Program Fragment 

***Declaring library entry point 

LOGICAL FUNCTION DBDATA (REQUST, DATUM) 
CHARACTER REQUST, DATUM 

IN LIBRARY DMI (ACTUALNAME = "F0RTRAN77DATA") 
END 

***Setting variables to initial values 
CHARACTER DATREQ *40 



***Declaring local variables 

LOGICAL RSLT 

***Invoking entry point 

DATREQ = "GET REAL EMP EMP-SSN" 
RSLT = DBDATA (DATREQ, DATBUF) 
IF (RSLT) CALL EXCEPT 

DATREQ = "GET REAL EMP EMP-DATE-HIRED" 
RSLT = DBDATA (DATREQ, DATBUF) 
IF (RSLT) CALL EXCEPT 

DATREQ = "GET STRING EMP EMP-LNAME" 
RSLT = DBDATA (DATREQ, DATBUF) 
IF (RSLT) CALL EXCEPT 



DATBUF 



*22 
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Section 5 

Handling Exceptions 



Whenever a call to a DMINTERPRETEK library standard entry point, data transfer 
entry point, or attribute setting entry point cannot be successfully or correctly 
completed, the DMSn software retxuns an exception word to the program. 

The exception word, also called a result descriptor, contains three items of information: 

• A value that can be used to determine if an error or exception occurred. (An 
exception affects only the application program that detected the exception. An error 
is caused by a problem within the database. An error affects all programts that 
request similar data management operations.) 

• The exception category and subcategory. 

• The structure number involved. 

The exception handling entry points allow you to return the exception word, the text of 
the exception message, or the name of the exception category to yova program. Your 
program locates the text of the message and the name (type) of the category by calling 
the DMSUPPORT library. 

Note: All the exceptions and errors that can be returned by the language 
extensions can also be returned by the interpretive interface. 
In addition, the interpretive interface can return a category of 
exceptions called INTLIBERROR. These errors are valid only for the 
interpretive interface. For more information about exceptions that 
might occur, refer to Appendix By 'DMSII Exceptions and Errors. " 

This section details the exception handling entry points by task. Each exception 
hanHling task with its Corresponding entry points are listed in Table 5-1. Use the 
heading for each listed task to locate the pages that details the entry point. For example, 
a description of the exception handling entry points ALGOLSTATUS, DBSTATUS, and 
FORTRAN77STATUS is found under "Returning the Exception Word." 
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Table 5-1. Exception Handling Entry Points to the DMINTERPRETER Library by Task 



Task 


Entry Points 


Returning the exception word 


ALGOLSTATUS 




DBSTATUS 




F0RTRAN77STATUS 


Returning the text of an exception message 


ALGOLEXCEPTIONTEXT 




DBEXCEPTIONTEXT 




F0RTRAN77EXCEPTI0NTEXT 


Identifying the type of exception 


ALGOLEXCEPTIONNAME 




DBEXCEPTIONNAME 




FORTRAN77EXCEPTiONNAME 



The disctission of each task incliides the following: 

• A brief explanation of the function of the entry point 

• Syntax diagrams and semantics that describe reqtdred parameters 

• Program fragments that illustrate 

- Declaring variables for the entry points 

- Invoking the entry point 

- Returning results from the DMINTERPRETER library 

- Handling exceptions returned by the entry point 

Unless otherwise noted, COBOL, COBOL74, and COBOL85 have the same 
reqiairements. 

Refer to Section 3, "Manipulating the Database,'* Section 4, "Transferring Data," and 
Section 6, "Restricting Calls to the Accessroutines," for information on standard entry 
points, data transfer entxy points, and attribute setting entry points, respectively. 

Note: Until the database is explicitly opened, any call on a standard 

entry point, a data transfer entry point, or an attribute setting entry 
point results in an error. However, your program can call the three 
eooception handling entry points and perform operations on the 
intrinsic data set DBSTRUCTURE whether the database is opened 
or closed. 
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Returning the Exception Word 

The status entry point returns the exception word for the last called entry point. The 
exception word contains three items: 

• A value that can be used to determine if an error or exception occurred 

• The exception category and subcategory 

• The structure niunber involved 

The exception word can be passed to the exception text entry point (to retrieve the text 
of the exception message) or to the exception name entry point (to retrieve the name of 
the exception category). 

Passing a Parameter 

For ALGOL and FORTRAN??, the status exception handling entry point has no 
required parameter. 

For COBOL, COBOL74, and COBOL85, your program needs an exception variable. 
Parameter Explanation 

<©(ception> A variable containing a value that signifies whether an exception 

occurred during the last entry point call. 

For COBOL, the variable must be declared at level 01 as a PIC 9(12) 
COMP-2 item. For COBOL74 and COBOL85, the variable must be 
declared at level 01 as a PIC 9(12) COMP item. 

Table 5-2 gives the exported names of the entry points, as well as the parameters and 
the data type of each parameter. 



Table 5-2. Returning an Exception Word 



Exported Name of 






Entry Point 


Parameter 


Data Type of Parameter 


ALGOLSTATUS 


Not applicable. 


Not applicable. 


DBSTATUS 


<exception> 


COMP-2 (COBOU 






COMP (C0B0L74 and C0B0L85) 


FORTRAN77STATUS 


• Not applicable. 


Not applicable. 



Program Examples 

The following program fragm^ts illustrate how to obtain an exception word &om the 
last called entry point. 
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ALGOL Pr(^am Fragment 

%Declaring local variables 

BOOLEAN 
STATUSRSLT; 

%Declaring library entry point 

LIBRARY DMI; 

BOOLEAN PROCEDURE DBSTATUS; 
BOOLEAN PROCEDURE DBSTATUS; 
LIBRARY DMI (ACTUALNAME="ALGOLSTATUS") ; 

%Invoking entry point 

STATUSRSLT: =DBSTATUS; 

COBOL, C0B0L74, or C0B0L85 Program Fragment 
***Declaring variables for COBOL 

01 EXCEPTION-WORD PIC 9(12) COMP-2. 

***Declaring variables for C0BOL74 and C0B0L85 

01 EXCEPTION-WORD PIC 9(12) COMP. 

***Invoking entry point 

CALL "DBSTATUS OF DMINTERPRETER" 
USING EXCEPTION-WORD. 

FORTRAN?? Pr(^m Fragment 

***Declaring library entry point 

LOGICAL FUNCTION DBSTAT () 

IN LIBRARY DMI (ACTUALNAME = "F0RTRAN77STATUS") 
END 

***Setting variables to initial values 
LOGICAL RESULT 
***Invoking entry point 
RESULT = DBSTAT 0 
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Returning the Text of an Exception IVIessage 

After the status operation rettims the exception word to the program, you can use the 
exception text operation to return and display the text of an exception message. 

The text of the message is returned from the DMSUPPORT library. The message is 
identified by the category, subcategory, and structure number in the exception word. 
(Refer to Appendix B, "DMSn Exceptions and Errors," for more information on 
categories and subcategories.) 

Notes: 

• A call on a status entry point must precede any call on an 
exception text entry point. 

• If you receive an error message during an exception text 
operation, check whether the DMSUPPORT library is currently 
unavailable. 



Passing Parameters 

There are two required parameters: a variable denoting whether an exception has 
occurred and a variable for the text of the message. 

Parameter Explanation 

<exception > A variable containing a value that signifies vt/hether an exception 

occurred during the last entry point call. 

For COBOL, the variable must be declared at level 01 as a PIC 9(12) 
COMP-2 item. For C0B0L74 and C0B0L85, the variable must be 
declared at level 01 as a PIC 9(12) COMP item. 

<t^ of exception A variable containing the cat^ory name, the structure name and number 
message > (if a structure is involved), and the tsct of the exception or error message. 

If the text cannot fit into the variable, the message is truncated. If the 
text does not fill the variable, it is padded with trailing blanks. 

If no ^ception has occurred, the variable contains the text NO 
EXCEPTION. 

Table 5-3 gives the data types for the parameters and the exported names of Hie entiy 
points. 
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Table 5-3. Returning tlie Text of an Exception l\Aessage 



Exported Name of Entry Point 


Parameter 


Data Type of Parameter 


ALGOLEXCEPTIONTEXT 


<exceptlon> 


BOOLEAN 




<text> 


STRING 


DBEXCEPTIONTEXT 


<exception> 


COMP-2 (COBOL) 






COMP (C0B0L74 and COBOL85) 




<text> 


DISPLAY 


F0RTRAN77EXCEPTI0NTEXT 


< exception > 


LOGICAL 




<text> 


CHARACTER 



Program Examples 

The following program fragments use an exception text operation to obtain an exception 
message. 

ALGOL Program Fragment 

%Declaring library entry point 
LIBRARY DMI; 

BOOLEAN PROCEDURE DBEXCEPTIONTEXT (EXCEPTION, MSG) ; 
VALUE EXCEPTION; 
BOOLEAN EXCEPTION; 
STRING MSG; 

LIBRARY DMI (ACTUALNAME="ALGOLEXCEPTIONTEXT") ; 

%Exception handling procedure 

PROCEDURE EXCEPTIONHANDLER; 
BEGIN 

STRING EXCEPTIONMSG; 
BOOLEAN STATUSRSLT; 

STATUSRS LT: =DBSTATUS ; 

DBEXCEPTIONTEXT (STATUSRSLT, EXCEPTIONMSG) ; 
WRITE (REMOTEFI LE ,<EXCEPTION_TEXT=">) ; 
WRITE (REMOTEFILE,<A80>,EXCEPTIONMSG); 
END OF EXCEPTIONHANDLER; 
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COBOL, C0B0L74, or C0B0L85 Program Fragment 



***Declaring variables for COBOL 



01 EXCEPTION-WORD 
01 EXCEPTION-MSG 



PIC 9(12) COMP-2. 
PIC X(80). 



***Declaring variables for C0B0L74 and C0B0L85 



01 EXCEPTION-WORD 
01 EXCEPTION-MSG 



PIC 9(12) COMP. 
PIC X(80). 



***Invoking entry point 

CALL "DBSTATUS OF DMINTERPRETER" 

USING EXCEPTION-WORD. 
CALL "DBEXCEPTIONTEXT OF DMINTERPRETER" 

USING EXCEPTION-WORD, EXCEPTION-MSG. 
MOVE EXCEPTION-MSG TO REMOTE-REC. 
WRITE REMOTE-REC. 



F0RTRAN77 Program Fragment 

***Declaring library entry point 

SUBROUTINE DBEXCT (EXCEPT, TEXT) 
LOGICAL EXCEPT 
CHARACTER TEXT 

IN LIBRARY DMI (ACTUALNAME = "FORTRAN77EXCEPTIONTEXT") 
END 

***Exception handling subroutine 

SUBROUTINE EXCEPT (RESULT) 

$INCLUDE "DATABASE/DMINTERPRETER" 20290000-20299999 

CHARACTER MSG *70 
LOGICAL RESULT 

RESULT = DBSTATO 

CALL DBEXCN (RESULT, MSG) 
WRITE (6, 200) MSG 

CALL DBEXCT (RESULT, MSG) 
WRITE (6, 200) MSG 
200 FORMAT (IX, A) 
RETURN 
END 
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Identifying the Type of Exception 



After tiie status operation returns the exception word to the program, can use an 
exception name operation to return the type of exception. Your program can then 
display the exception category. 

The Accessroutines can return 21 types of exceptions. Each type is considered a distiQct 
major category. The category name is returned from the DMSUPPOKT library. Refer to 
Appendix B, "DMSIE Exceptions and Errors," for more information on categories and 
subcategories. 

Notes: 

• A call on a status entry point must precede any call on an 
exception name entry point. 

• If you receive an error message during an exception name 
operation, check whether the DMSUPPORT library is currently 
unavailable. 

Passing Parameters 

The exception name entry points have two required parameters: a variable denoting 
whether an exception has occurred and a variable containing the name of the type of 
exception. 

f^rameter Explanation 

<exception > A variable containing a value that signifies whether an exception 

occurred during the last entry point call. 

For COBOL, the variable must be declared at level 01 as a PIC 9(12) 
COMP-2 item. For COBOL74 and COBOL85, the variable must be 
declared at level 01 as a PIC 9(12) COMP item. 

< name of A variable containing the name of the exception. If the name cannot fit 

exception into the variable, the name is truncated. For example, if the variable 

category> holds only five characters, the cat^ory OPENERROR is stored as 

OPENE. If the name does not fill the variable, trailing blanks are added. 

If no exception has occuned, the variable contains the text iSTO 
EXCEPTION. 

Table 5-4 gives the data types for the parameters and the exported names of tiie entry 
points. 
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Table 5-4. Identifying the Type of Exception 



Exported Name of Entry Point 


Parameter 


Data Type of Parameter 


ALGOLEXCEPTIONNAIVIE 


<exception> 


BOOLEAN 




<name> 


STRING 


DBEXCEPTIONNAME 


<exception> 


COiy/IP-2 (COBOL) 






COUP {COBOL74 and COBOL85) 




<name> 


DISPLAY 


FORTRAN77EXCEPTIONNAME 


< exception > 


LOGICAL 




<name> 


CHARACTER 



Program Examples 

The follo^dng program fragments use an exception name operation to obtain the type of 
exception. 

ALGOL Program Fragment 

%Declaring library entry point 
LIBRARY DMI; 

BOOLEAN PROCEDURE DBEXCEPTIONNAME (EXCEPTION, CATEGORY) ; 
VALUE EXCEPTION; 
BOOLEAN EXCEPTION; 
STRING CATEGORY; 

LIBRARY DMI (ACTUALNAME="ALGOLEXCEPTIONNAME") ; 

%Exception iiandling procedure 

PROCEDURE EXCEPTIONHANDLER; 
BEGIN 

STRING EXCEPTIONMSG; 
BOOLEAN STATUSRSLT; 

STATUSRSLT : =DBSTATUS ; 

DBEXCEPTIONNAME (STATUSRSLT , EXCEPTIONMSG) ; 
WRITE(REM0TEFILE.<EXCEPTI0N_NAME="".A14>.EXCEPTI0NMSG>); 
END OF EXCEPTIONHANDLER; 
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COBOL, C0B0L74, or C0B0L85 Program Fragment 



***Declarir)g variables for COBOL 



01 EXCEPTION-WORD 
01 EXCEPTION-NAME 



PIC 9(12) COMP-2. 
PIC X(14). 



***Declaring variables for C0B0L74 and C0B0L85 



01 EXCEPTION-WORD 
01 EXCEPTION-NAME 



PIC 9(12) COMP. 
PIC X(14). 



***Invoking entry point 

CALL "DBSTATUS OF DMINTERPRETER" 

USING EXCEPTION-WORD. 
CALL "DBEXCEPTIONNAME OF DMINTERPRETER" 

USING EXCEPTION-WORD, EXCEPTION-NAME. 
MOVE EXCEPTION-NAME TO REMOTE-REC. 
WRITE REMOTE-REC. 



FORTRAN?? Program Fragment 

***Declaring library entry point 

SUBROUTINE DBEXCN (EXCEPT, TEXT) 
LOGICAL EXCEPT 
CHARACTER NAME 

IN LIBRARY DMI (ACTUALNAME = "F0RTRAN77EXCEPTI0NNAME") 
END 

***Exception handling subroutine 

SUBROUTINE EXCEPT (RESULT) 

$INCLUDE "DATABASE/DMINTERPRETER" 20290000-20299999 

CHARACTER MSG *70 
LOGICAL RESULT 

RESULT = DBSTATO 

CALL DBEXCN (RESULT,MSG) 
WRITE (6, 200) MSG 

CALL DBEXCT(RESULT.MSG) 
WRITE (6, 200) MSG 
200 FORMAT (IX .A) 
RETURN 
END 
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Section 6 

Restricting Calls to the Accessroutines 



This section details the attribute setting entry point you use to restrict the number of 
times the DMINTERPKETER library can call the Accessroutines to complete a find, 
lock, or secure operation. 

The discussion includes the foUovnng: 

• A brief explanation of the function of the entry point 

• An explanation of the required parameters 

Read Section 2, "Accessing the Interpretive Interface," for an explanation of how each 
language accesses the interpretive interface and invokes an entry point. 

Passing Parameters 

Each language has only one attribute setting entry point. (COBOL, COBOL74, and 
COBOL85 have the same requirements.) The entry point has two parameters: limit 
type and limit value. 

Parameter Explanation 

<limit type> A string parameter that specifies the type of limit to fc)e set (what 

operation to restrict). 

Note: The only valid limit type is FINDLIMIT. It restricts 
find, lock, and secure (^radons and prevents long 
linear searches. Both record and structure find, lock, 
and secure operations are restricted. 

<limit value> An int^er string parameter that specifies the maximum numt)er of times 

the DMINTERPRETER can call the Accessroutines to perform a find, 
lock, or secure operation. The limit value has two restrictions: 

• When the DMINTERPRETER is first initialized, FINDLIMIT is set to 
the default value of 0 (zero). A zero value disables the FINDLIMIT 
mechanism, permitting a linear search of the entire data set. 

• N^ative values are not allowed. 

Table 6-1 gives the exported names of tiie entry points, as well as the parameters and 
the data type of each parameter. 
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Table 6-1. Attribute Setting Entry Points - Restricting Calls to Accessroutines 



Exported Name of Entry Point 


Parameter 


Data Type of 
Parameter 


ALGOLSETLIMIT 


< limit type> 


STRING 




< limit value> 


STRING 


DBSETLIMIT 


< limit type> 


DISPLAY 




<limit value> 


DISPLAY 


FORTRAN77SETLIMIT 


< limit typo 


CHARACTER 




< limit vaiue> 


CHARACTER 



Note: 



• If you specify an invalid limit type, the Accessroutines returns 
INTLIBERROR33. 

• If the DMINTERPRETER library exceeds the limit value, the 
Accessroutines returns INTUBERROR 35. 

Refer to Appendix B, ''DMSII Exceptions and Errors," for more information on 
INTLIBERROR errors. 

Program Examples 

The following ALGOL, COBOL, and FORTRAN?? program fragments limit find, lock, 
and secure operations (on both records and structures), overriduig the system default. 

Li each program fragment the limit type is FINDLIMIT and the limit value is 9. 
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ALGOL Program Fragment 

%Dec1anng local variables 
STRING 

limit_type, limit_value; 
boolean" 

RSLT; 

%Assigning values to parameters 

LIMIT_TYPE:="FINDLimT"; 
LIMIT_VALUE:="9"; 

%Declaring library entry point 

LIBRARY DMI; 

BOOLEAN PROCEDURE DBSETLIMIT(LIMITTYPE, LIMITVALUE) 
STRING LIMITTYPE, LIMITVALUE; 
LIBRARY DMI (ACTUALNAME="ALGOLSETLIMIT") ; 

%Invoking entry point 

RSLT:=DBSETLIMIT(LIMIT_TYPE, LIMIT_VALUE) ; 
IF RSLT 

THEN EXCEPTIONHANDLER; 



COBOL, C0B0L74, or C0B0L85 Program Fragment 

***Decl ari ng vari abl es 

01 LIMIT-TYPE PIC X(17) VALUE IS "FINDLIMIT". 

01 LIMIT-VALUE PIC X(17) VALUER IS SPACES. 

01 RESULT PIC 9(1) COMP-1 VALUE IS 0. 

★★★Invoking entry point 

MOVE "9" TO LIMIT-VALUE. 

CALL "DBSETLIMIT OF DMINTERPRETER" 

USING LIMIT-TYPE, LIMIT-VALUE 

GIVING RESULT. 
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F0RTRAN77 Program Fragment 

***Declaring library entry point 

LOGICAL FUNCTION DBSETLIMIT (LTT, LTV) 
CHARACTER LTT, LTV 

IN LIBRARY DMI (ACTUALNAME="FORTRAN77SETTLIMIT") 

***Setting variables to initial values 

CHARACTER LLT *9 /"FINDLIMIT"/ 
LTV *2 /"9'7 

***Declaring local variables 

LOGICAL RSLT 

***Invoking entry point 

RSLT = DBSETL(LTT,LTV) 
IF (RSLT) CALL EXCEPT 
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Section 7 

Determining the Database Structure 



The DMINTERPEETER Kbrary contains an intrinsic, read-only data set named 
DBSTRUCTURE. This data set holds structural information about the database that 
allows your application program to do the following: 

• Determine the database structure at run time. 

• Use general-purpose routines that can access any database and yet be 
data-independent. 

Generating the DBSTRUCTURE Data Set 

As one of its options, the program BUILDINQ can automatically generate the 
DBSTRUCTURE data set when the DMINTERPRETER library is compiled. If the data 
set is generated, it need not be declared in the DASDL description of the database. 

Notes: 

• If the DASDL description of the database contains a 
user-declared data set named DBSTRUCTURE, BUILDINQ 
cannot generate the intrinsic data set DBSTRUCTURE. 

• If you are using A Series Extended Retrieval with Graphic 
Output (ERGO), you must generate the intrinsic data set 
DBSTRUCTURE. 

For more information on how to use BUILDINQ to generate the data set, refer to 
Appendix A, "Generating the DMINTERPRETER library." 

Accessing the DBSTRUCTURE Data Set 

Unlike other data sets, your application program can access the intrinsic 
DBSTRUCTURE data set before opening the database. However, at all times, only 
three operations can be performed on the DBSTRUCTURE data set: find, get, and set. 

To access iten^ in the DBSTRUCTURE data set, use a find operation entry point. 
For example, the following call to D6FIND locates the next required item in 
DBSTRUCTURE: 

DBFIND ("NEXT", "DBSTRUCTURE", "ITEM-REQUIRED") 



8600 0155-000 



7-1 



Determining the Database Structure 



Describing the Structure and Contents of 
DBSTRUCTURE 

DBSTRUCTURE contains an entry for each data set, set, subset, access, item, and link 
in the database. No sets or subsets span DBSTRUCTURE. 

DBSTRUCTURE behaves as if it had the following DASDL description: 
DBSTRUCTURE DATA SET 



(DB-ID FIELD(16) REQUIRED; 

DB-OWNER FIELD (16) REQUIRED; 

DB-NAME ALPHA(17) REQUIRED; 

DB-TYPE ALPHA(17) REQUIRED; 

% ITEMS PRESENT WHEN DB-TYPE = "DATASET" 



DATASET-SUBTYPE ALPHA(17); 
% ITEMS PRESENT WHEN DB-TYPE = "SET" 



SET-SUBTYPE ALPHA(17); 
SET -ACCESS -METHOD ALPHA(17); 
SET-SPANS-DATASET NUMBER(4); 

% ITEMS PRESENT WHEN DB-TYPE = "ITEM" 

ITEM-SUBTYPE ALPHA(17); 

ITEM-SUBSCRIPTS NUMBER (2) ; 

ITEM-OCCURS NUMBER (4); 

ITEM-OWNER-GROUP NUMBER(4) ; 

ITEM-REQUIRED BOOLEAN; 

ITEM-SIZE NUMBER(4); 

ITEM-SCALE- FACTOR NUMBER{2); 

ITEM-SIGNED BOOLEAN; 

ITEM-KEY-CUSS ALPHA(17); 

ITEM-RECORD-TYPE NUMBER (3); 

% ITEMS PRESENT WHEN DB-TYPE = "LINK" 

LINK-TO-DATASET NUMBER (4) ; 

LINK-OCCURS NUMBER (4) ; 

); 

As described in Table 7-1, the first four items in the record (DB-ID, DB-OWNER, 
DB-NAME, and DB-TYPE) uniquely identify the database. These items always have 
nonnull values; they are required items. When a record is stored in the data set, the 
system tests aU required items. If a required item contains a nuU value, the storing 
program receives an exception and does not store the record. You can use the required 
option to ensure that all data items, with tiie exception of Boolean items, are assigned a 
nonnull value. 
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Table 7-1. DBSTRUCTURE Items 


Item 


Description 


DB-ID 


Contains a positive numlDer tliat uniquely identifies eacli component 
in the database. DB-ID allows records in DBSTRUCTURE to be 
associated with each other. Items In more than one variable record 
type are considered to be different entities, each with a different 
DB-ID. 


DB-OWNER 


Contains the DB-ID of the data set that owns this entry. DB-OWNER 
is 0 (zero) for the global data entry. All disjoint structures and global 
data items have the DB-ID for global data. 


DB-NAME 


Contains the name of the entity. Trailing blanks are added, if 
needed. 


DB-TYPE 


Contains a string describing the type of the entity. Valid values and 
their explanations are as follows: 

• DATASET. Specifies a data set. 

• SET. Specifies a set, subset, or access. 

• ITEM. Specifies a data item. 

• LINK. Specifies a link. 



Entities are assigned nonnull and null values as follows: 

• If the DB-TYPE is DATASEX the item DATASET-SUBTYPE has a nonnull value. 
All SEX ITEM, and LINK entities are null. 

• If the DB-TYPE is SET, the items SET-SUBTYPE, SET-ACCESS-METHOD, and 
SET-SPANS-DATASET have nonnull values. All DATASEX ITEM, and LINK 
entities are nulL 

• If the DB-TYPE is ITEM, all items beginning with "ITEM-" have nonnull values. All 
DATASEX SEX and LINK entities are nuIL 

• If the DB-TYPE is LINK, the items LINK-TO-DATASET and LINK-OCCUKS have 
nonnull values. All DATASET, SET, and ITEM entities are null 

Notes: 

• All sets with group keys haue the following two entries in the 
DBSTRUCTURE intrinsic data set' 

- An entry that lists the group as its key 

- An entry that lists the elementary items as its keys 

• Each database also has cm entry for global data. This entry can 
be used to find all the disjoint structures and global data items 
in the database. 
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Tables 7-2 through 7-5 describe the items associated with each value of DB-TYPE. 

• The items for DATASET are described in Table 7-2. 

• The items for SET are explained in Table 7-3. 

• The items for ITEM are shown in Table 7-4. 

• The items for LINK are given in Table 7-5. 



Table 7-2. DBSTRUCTURE Items for a DB-TYPE of DATASET 



item 


Description 


DATASET-SUBTYPE 


Contains a string describing tlie type of a data set. Valid values and 




their explanation are as follows: 




• STANDARD. Identifies a data set that stores new records in 




areas vacated by old records. 




• RANDOM. Identifies a data set that uses a function on an 




Access to retrieve records. 




• ORDERED. Identifies a data set that orders records in the 




sequence defined by the alphanumeric key. 




• UNORDERED. Identifies a data set that stores records in an 




unpredictable order. 




• GLOBAL Identifies a data set that locates all disjoint structures 




and global data items in the database. 




• DIRECT. Identifies a data set that uses an index known as an 




access. 




• RESTART. Identifies a data set that the prc^rams access during 




recovery. 




• COMPACT. Identifies a data set that removes null items and 




trailing blanks from alpha items before storing records on disk. 




• STRUCTURE. Identifies the DBSTRUCTURE itself. 



The different types of data sets are detailed in the DMSH Technical Overview. 
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Table 7-3. DBSTRUCTURE Items for a DB-TYPE of SET 



Item 


Description 


SET-SUBTYPE 


Contains a string describing the type of a set. Valid values and their 
explanations are as follows: 




• 


SET. Identifies a structure that permits logical sequence access. 
It contains one entry for each record in the data set. The set 
can be disjoint or embedded. Records are indexed through a 
key in the data set. 




• 


SUBSET, identifies a structure similar to a set, except it only 
indexes certain members of data set. A subset can be 
automatic or manual. 




• 


ACCESS. Identifies a method of retrieving records from direct, 
random, and ordered data sets in the order defined by a key. 
Accesses do not physically exist on disk. 


SET-SEARCH- 
METHOD 


Contains a string describing the accessing method used by a set. 
N^lld values and their explanations are as follows: 




• 


DIRECT. Specifies direct data set accesses. 




• 


BINARY. Specifies ordered data set accesses, and index 
sequential and ordered list sets. 




• 


HASH. Specifies random data set accesses and index random 
sets. 




• 


LINEAR. Specifies unordered data set accesses and bit vector 
sets. 


SET-SPANS-DATASET 


Contains the DB-ID of the data set spanned by a set. 



Constilt the DMSII Technical Overview for an explanation of types of sets. Read the 
DMSII Application Programming Guide for an explanation of search methods and 
techniques. 
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Table 7-4. DBSTRUCTURE Items for a DB-TYPE of ITEM 



Item 


Description 


ITEM-SUBTYPE 


Contains a string describing tlie type of an item. Valid values and 
tiieir explanations are as follows: 

• ALPHA. Identifies words and characters stored as EBCDIC 
characters. 

• GROUP, identifies a collection of related items. The items can 
be alphabetic or numeric items. 

A PIPI r*\ Irlonfifioc from 1 fr\ P^/v^losin v/oliioc or stn iincicrnoH 
V rluUL^. lUCIILIIiCo liUlll 1 LU *tO OUUlCdil VolUcb Ul all UllolgllCVJ| 

nonn^ative integer up to 48 bits long. 

• NUMBER Identifies intpc^prs and fractions with or without 
signs. 

• REAL. Identifies single precision floating-point numbers. 

• BOOLEAN. Identifies true or false values. 

• COUNT. Identifies a value that tracks the number of links 
pointing to the record. 

• TYPE. Identifies the record type of the current record. 

• POPULATION. Identifies a value that estimates the expected 

size of the data set. 


ITEM-SUBSCRIPTS 


Contains the number of subscripts required when the item is used. 
If no subscripts are required, ITEM-SUBSCRIPTS is 0 (zero). 


ITEM-OCCURS 


Stores the subscript limit for an item declared with an OCCURS 

uiausc III LUC L/r\OL/L. UCauii^Juuii. 

Notes: 

• If ITEM-SUBSCRIPTS is 0 (zero), 
ITEM-OCCURS contains a null value. 

• Items that have a nonzero value in 
ITEM-SUBSCRIPTS and a null value in 
ITEM-OCCURS are nonoccurring items. 

• To find the other subscript limits for 
multiple-subscripted items, inspect the 
ITEM-OCCURS entries in which DB-W 
equals ITEM-OWNER-GROUP 



continued 
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Table 7-^. DBSTRUCTURE Items for a DB-TYPE of ITEM (cent.) 



Item 


Description 


ITEM-OWNER- 
GROUP 


Contains the DB-ID of the next higher group or field that contains an 
item. The DB-ID can be used to determine 

• The index limit for items in occurring groups and fields. 

• The items that belong to a given group or field. 

If an item does not belong to a group or field, ITEM-OWNER-GROUP 
is 0. 


ITEM-REQUIRED 


Contains the value TRUE If the entity is a required item. Otherwise, 
the value is FALSE. 


ITEM-SIZE 


Contains the declared length of a number, field, alpha, or group item 
in hexadecimal digits, bits, EBCDIC bytes, and bytes, respectively. 

JVbfe: Ordinarily, ITEM-SIZE does not include any 

spaces for signed values. However, it does include 
spaces for group items containing signed number 
items. 


ITEM-SCALE-FACTOR 


fVintainQ thp rfpplarpH niimhpr nf HiaitQtn thp ricrht nf thp Hppimsil 

point for number items and real items that have a scale factor 
declared in the DASDL description. 

The value of a number cannot exceed the following: (The symbol ** 
is used to represent the exponent.) 

10**[(ITEM-SIZE) - (ITEM-SCALE-FACTOR)] 

Unless the real value is declared without precision, the real value 
must be less than the following: 

549755813887 . 5/10** ( ITEM-SCALE-FACTOR) 


ITEM-SIGNED 


Contains the value TRUE for a number item or real item if the item 
can be n^atlve (in other words, declared as signed in the DASDL 
description). It contains the value FALSE for a number or real item 
that cannot be signed. 



continued 
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Table 7-4. DBSTRUCTURE Items for a DB-TYPE of ITEM (cent.) 



Item 


Description 


ITEM-KEY-CLASS 


Contains a string indicating tfie key status of an item In a spanning 
set. Valid entries and their explanations are as follows-. 

• MAJOR. Identifies the item as the major key of a spanning set 
or access. (The major key is defined as the first key listed in the 
declaration of the set.) 

• MINOR. Identifies the items as a key of the set. The item Is not 
the major key of a spanning set or access. 

• DATA. Specifies that the item appears only as key data in 
spanning sets or accesses. 

• NONE. Specifies that the item does not appear in the key area 

of any access or spanning set. 


ITEM-RECORD-TYPE 


Contains the record type of an item. The ITEM-RECORD-TYPE is 0 
(zero) for items in fixed-format records or in the fixed part of 
variable-format records. 

Note: Because an item with a particular DB-ID can only 
be in records of one type, any other item of the 
same name in a different record type has a 
different DB-ID. 


ITEM-USAGE 


Contains a string describing the usage of an item. Valid values are 
EBCDIC and KANJI. 


Consult the DMSII Technical Overview for information on types of items, the OCCURS 
clause, key status, key items, and record types. 


Table 7-5. 


DBSTRUCTURE Items for a DB-TYPE of LINK 


Item 


Description 


LINK-TO-DATASET 


Contains the DB-ID of the data set to which a link points. 


LINK-OCCURS 


Contains the limit of the OCCURS clause for a link, if 
LINK-OCCURS is 0 (zero), no OCCURS clause was present in the 
declaration of the link. 



The DMSn Technical Overview contains detailed information about links. 
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Appendix A 

Generating the DM INTERPRETER Library 



To use the interpretive interface, each database must have its own custom-tailored 
DMINTERPRETER library. You can use the program BUILDINQ to generate the 
library interactively or from a Work Flow Language (WFL) job deck. 

Usually, a DMINTERPRETER library is generated only once - after the DASDL so\irce 
code for the database is compiled. However, if there is a directory-level mismatch or if 
you use the REORGANIZATION program to make physical changes to the database 
description, you need to generate the DMINTERPRETER library again. (Consult the 
DMSII Utilities Operations Guide for specifics of the REORGANIZATION program.) 

Capabilities of the BUILDINQ Program 

The BUILDINQ program does the following: 

• Associates a cycle, version, and timestamp with a copy of each generated file 

• Sets either the DASDL option ZIP or the RECOVER option NOZIP 

• Allows your application program to interface with 

- An entire physical database 

- Selected parts of a database 

- A logical database 

- A mayimuTn of 255 structures plus global data 

• Specifies if the database can be compiled for inquiry only or for inquiry and update 

Files Associated with a DMINTERPRETER Library 

Table A-1 lists the files associated with a DMINTERPRETER Ubraiy. 
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Table A-1. Files Associated with a DIVIINTERPRETER Library 



File Name 


Use 


SYMBOLyBUILDINQ 


Symbolic file of the program compiled to produce 
OBJECT/BUILDINQ. 

SYMBOL/BUILDINQ can be compiled using DMALGOL 
by equating the DMALGOL file TAPE to the file 
SYMBOL/BUILDINQ. 


SYSTEA/I/BUILDINQ 


Object code file for SYMBOL/BUILDINQ. 

SYSTEM/BUILDINQ builds a directory for the portion 
of the database that DMINTERPRETER can access. 
The directory, named 

DMIDIRECTORY/< database name>, is compiled and 
included In the DMINTERPRETER code file for 
run-time interpretation of the database structure. 


DATABAS^/DMINTERPRETER 


Symbolic file for DMINTERPRETER. 

DATABASE/PROPERTIES and 
DMIDIRECTORy/<database name> are included in 
this symbolic file. 


SYSTEM/DMINTERFACE 


An external coroutine, called by the compilers, to 
extract and check information from 
DESCRIPTION/<database name>. 


DATABASE/PROPERTIES 


Each statement in this file defines some aspect of the 
database. The file is included in both the DASDL 
compliation and DATABAS^DMINTERPRETER. 


OESCRIPTION/<database name> 


File containing a complete description of the database 
in encoded form. This file is the output from a DASDL 
compilation and is used by SYSTEM/DM INTERFACE. 


DMINTERPRETER/<database name> 


The generated DMINTERPRETER code file. 


DMIDIRECTORY/<clatabase nanie> 


The intermediate compiler input file, it is produced by 
SYSTEM/BUILDINQ and included by 
DATABASE/DMINTERPRETER. 
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Figure A-1 illiistrates the relationships among the files. 



DESCRIPTION/<database name> 
(DASDL file) 




DATABASE/ PROPERTIES 
(DMSII file) 




DATABASE/DMINTERPRETER 
(DMSII file) 



SYSTEM/BUI LDINQ 




SYMBOL/BUI LDINQ 




SYSTEM/ DMINTERFACE 
(DMSII file) 




DMIDIRECTORY/<database naine> 




DMINTERPRETER/«latabase name> 



Figure A-1. Relationship of BUILDINQ Files 
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Ensuring Directory-Level Consistency between Files 

In order for you to use the interpretive interface, the directory level of the intermediate 
compiler input file DMTDIRECTORY/ < database name > and the directory level of the 
symbolic program file DATABASE/DMINTERPRETER must be the same. 

During compilation of the interpretive interface, the directory levels are checked to 
ensure consistency. If a level mismatch is found, the error count for the compiler 
increases by 1, and the following error message is displayed: 

DMIDI RECTORY LEVEL MISMATCH 

You cannot successfully generate the DMINTERPRETER library with a directory-level 
mismatch. To correct the problem, renm the BUILDINQ program to create a new 
DMIDIRECTORY file with the correct directory level 



Generating the DMINTERPRETER Library Interactively 

You can use the BUILDINQ program to interactively generate a DMINTERPRETER 
library from a remote terminal and to set the RECOVER option NOZIP. 

By default, the DASDL option ZIP is set. The ZIP option causes automatic compilation 
of the DMINTERPRETER program; the NOZIP option inhibits automatic compilation. 
When the NOZIP option is set, BUILDINQ builds a Work Plow Language (WFL) deck 
for compiling DMINTERPRETER. Use the NOZIP option if you want to set any of the 
following: 

• Class specification 

• Family specification 

• Usercode specification 

• Fetch specification 

• Job attribute ass^nment 

The procedure to use the default of ZIP and the procedure to set NOZIP are basically 
the same. The procedure for using the default is explained in ^Remote Generation 
Using the ZIP Option." The daSeriag steps needed to set the NOZIP option are 
explained in ''Remote Generation Using the NOZIP Option." 

Note: All input to the BUILDINQ program must be entered in uppercase 
letters. If you use any lowercase letters, you are reprompted. 
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Remote Generation Using the ZIP Option 

Use the followii^ basic procedure to execute BUILDINQ and to use the default ZIP 
option: 

1. Initiate the BUILDINQ program. 

2. Select the database. 

3. Select a view of the database. 

4. If applicable, select data sets. 

5. If applicable, enter the name of a logical database. 

6. Determine the compiled access mode for the DMINTERPRETER library. 

7. If applicable, rename hyphenated logical database name. 

8. Enter a database name for the DMINTERPRETER code ffle. 

9. Enter compilation queue. 

10. Check for verification message. 

These 10 steps are detailed in the following text, including an explanation of when they 
apply. 

Consult the DMSUDASDL Reference Mcaiucd and the DMSII Utilities Operations 
Guide for more information about the ZIP option. 

Step 1. Initiating the BUILDINQ Program 

Begin executing the BUILDINQ program usii^ the RUN command. (RUN can be 
abbreviated as R or RU.) 

R BUILDINQ 

Step 2. Selecting the Database 

Each database must have its own, custom DMINTERPRETER libraiy. At the following 
prompt, enter the name of the database: 

WHAT DATABASE? 

Notes To use the NOZIP option, follow the st^s shown in "Remote 
Generation Using the NOZIP Option" in this section before 
proceeding to Step 3. 
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Step 3. Selecting a View of the Database 

You can generate the DMINTERPRETER libraiy for the physical database, disjoint data 
sets, or a logical database. At the follovting prompt, enter the number for the database 
option you want: 

WHICH OPTION? 

1 TOTAL DATABASE 

2 SELECTED DATASETS 

3 LOGICAL DATABASE 

Note: If no logical databases are declared for the specified database, 
option 3 is not displayed. 

As shown in the following table, your entry determines the subsequent sequence of 
prompts: 

Option Result 

1 Accesses the physical database— all database structures, Including the 
intrinsic data set DBSTRUCTURE. 

The program skips steps 4 and 5; it resumes at "Step 6. Determining the 
Compiled Access Mode for the DMINTERPRETER." See Figure A-2. 

2 Accesses only those disjoint data sets that are interactively selected. 
The prc^ram continues at "Step 4. Selecting Data Sets." See Figure A-3. 

3 Accesses only a logical database. The logical database represents only parts 
of the database to be used for limited purposes. 

The program skips step 4 and continues at "Step 5. Entering the Name of a 
Logical Database." See Figure A-4. 

The following three flowcharts, A-2, A-3, and A-4, illuslrate how the sequence of steps 
differs, depending on your choice. 
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Figure A-2 is a flowchart for compiling a DMINTERPRETER library for the total 
database. 



Initiate 
BUILINQ 



Enter 
database name 



Sel ect 
TOTAL DATABASE 
option 



Select 
access mode 



Sel ect 
database name for 
DMINTERPRETER/<database name> 



Enter 
compilation queue 



Wait for 
verification message 



(See step 1) 



(See step 2) 



(See step 3) 



(See step 6) 



(See step 8) 



(See step 9) 



(See step 10) 



Figure A-2. Compiling a DMINTERPRETER Library for the Total Database 



8500 0155-000 



A-7 



Generating the DMINTERPRETER Library 



Figure A-3 is a flowchart for compiling a DMINTERPRETER library for selected data 
sets. 



Initiate 

BUILINQ 



Enter 
database name 



Sel ect 
SELECTED DATASETS 
option 



Exclude and include 
data sets 



Select 
access mode 



Select 
database name for 
DMINTERPRETER/<database naroe> 



Enter 
compilation queue 



Wait for 
verification message 



(See step 1) 



(See step 2) 



(See step 3) 



(See step 4) 



(See step 6) 



(See step 8} 



(See step 9) 



(See step 10) 



Figure AS. Compiling a DMINTERPRETER Library for Selected Data Sets 
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Figure A-4 is a flowchart for compiling a DMINTEKPRETER library for a logical 
database. 



Initiate 
BUILINQ 



Enter 
database name 



Select 
LOGICAL DATABASE 
option 






Enter name of 
logical database 






Select 
access mode 







(See step 1) 



(See step 2) 



(See step 3) 



(See step 5) 



(See step 6) 



Rename 
logical database 



Yes 



Logi cal 
'database name 
hyphenated 



No 



Sel ect 
database name for 
DMINTERPRETER/<database name> 



Enter 
compilation queue 



Wait for 
verification message 



(See step 7) 



(See step 8} 



(See step 9) 



(See step 10} 



Figure A^. Compiling a DMINTERPRETER Library for a Logical Database 
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Step 4. Selecting Data Sets 

Ifyou choose to generate a DMINTERPRETER library for selected data sets, 
BUHiDINQ displays the name of each digoiat data set, one at a time. After each data 
set name is shown, BUILDINQ displays Uie following prompt: 

FOR FOLLOWING DATASETS ENTER: 



E (OR EMPTY INPUT) TO EXCLUDE FROM SOFTWARE 



I TO INCLUDE INTO SOFTWARE 
C TO INDICATE DONE 
* TO TERMINATE 



By entering E or I, you decide whether to exclude or include each digoint data set. 

By entering C or an asterisk (*), you signal the BUILDINQ that you want to terminate 
the run. 

• To terminate the run and generate a DMINTERPRETER library for the 
included data sets, as well as deciding ifyou want to include the intrinsic data set 
DBSTRUCTURE, enter a C. 

• To terminate the run without generating any DMINTERPRETER library, enter the 
asterisk. 

Option Result 

E Excludes the data set. 

null entry Excludes the data set. 

I Includes the data set. 

C Indicates that all desired disjoint data sets have been included. 

BUILDINQ then asks if you want the intrinsic data set DBSTRUCTURE 
included with the selected data sets. Enter YES or NO. 

* Terminates the run without generating a DMINTERPRETER library: 



Note: DBSTRUCTURE is an optional intrinsic data set that hold 

structural infbrmaiion about the database. DBSTRUCTURE can be 
accessed before the database is opened. 

Ifyou use Extended Retrieval with Graphic Output (ERGO) on the 
database, you must explicitly include the DBSTRUCTURE data set 
using the I option. 

For more information about the DBSTRUCTURE data set, read 
Section 7, ^^Determining the Database Structure. " 

Once you have selected the data sets and dedded whether to include the 
DBSTRUCTURE data set, BUILDINQ skips step 5 and continues at step 6. 



A-10 



8600 0155-000 



Generating the DMINTERPRETER Library 



Step 5. Entering the Name of a Logical Database 

At step 3 you can narrow the access to a logical database only. The logical database must 
be identified by name. At the following prompt, enter the name of the logical database: 

LOGICAL DATABASE NAME? 

Note: If the logical database contains an embedded. set that is invoked more 
than once, a remap error can occur. 

Step 6. Determining the Compiled Access Mode for the DMINTERPRETER Library 

A DMINTEKPRETER library can be compiled with inquiry-only access (read-only) or 
with both inquiry and update access. At the following prompt, enter the access mode you 
want for the DMINTERPRETER library: 

INQUIRY ONLY (YES OR NO)? 

The following table gives the result of each entry: 
Option Result 

YES Programs that access the database cannot create, delete, or update records; 

the programs can report data. 

NO Programs that access the database can create, delete, update, or report 

data. 

Note: If you compile a DMINTERPRETER library with an inquiry-only 
access, any attempt by a program to open a database with an OPEN 
UPDATE command results in an UNKNOWN OPEN TYPE error. 
Attempts to create, delete, or update records result in READONLY 
errors. 

If yotir logical database name (as entered in step 5) has no hyphen (-), BUILDINQ goes 
to step 8 and then step 9. If your database name has a hyphen, BUILDINQ proceeds to 
step 8, where you identify the interpreter library, and then proceeds to step 9. 

Step 7. Renaming Hyphenated Logical Database Names 

The BUILDINQ program uses the name of the database as part of the name for the 
DMINTERPRETBR code file DMINTERPRETER/ < database name > . The database 
name cannot contain any hyphens. Therefore, if the lo^cal database name entered at 
step 4 contains a iQ^hen, BUHDINQ displays the following prompt: 

INTERPRETER NAME? 

Enter a. name consisting of from 1 to 11 identifiers separated by slashes. Each identifier 
can contain from 1 to 17 alphanimieric characters only. For example, the database 
ACCOUNTING/PAYROLL 5 has two identifiers: ACCOUNTING and PAYROLLS. 
Each identifier is separated by a slash. Each identifier is less than 17 alphanumeric 
characters. 
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Note: If a file with the same name already exists, it is replaced by the newly 
compiled file. 

BUDLiDINQ then proceeds to step 9. 



Step 8. Entering a Database Name for the DMINTERPRETER Code File 

At the following prompt, enter the database name to be used in creating the generated 
DMINTERPRETER code file DMINTERPRETER/ < database name > : 

INTERPRETER NAME (NULL FOR DEFAULT)? 

You can either enter an imhyphenated name or use the default —the name you entered 
in step 2. If you enter a name, the name can consist of from 1 to 11 identifiers separated 
by slashes. Each identifier can contain 1 to 17 alphanumeric characters only. For 
example, the database BRANCHES/OVERSEAS/EUROPE has three identifiers: 
BRANCHES, OVERSEASA, and EUROPE. Each identifier is separated by a slash. Each 
identifier is less than 17 alphanumeric characters. 



Entry Result 

<database BUILDING uses this database name when it generates the code file 

name> DMINTERPRETER/<database name>. 

null BUILDING uses the <clatabase name> you entered in step 2 when it 



generates the code file. 

Note: If a file with the same name already exists, it is replaced by the newly 
compiled file. 

Step 9. Entering the Compilation Queue 

At the following prompt, enter the number of the queue where the DMINTERPRETER 
library should be compiled: 

WHAT QUEUE (NULL FOR DEFAULT)? 

You can use the system default queue or.select a specific queue: 
Option Result 

null BUILDING compiles DMINTERPRETER in the system default queue. 

<queue BUILDING compiles DMINTERPRETER in the specified queue. 

numt)er> 

Step 10. Displaying the Verification Message 

The BUILDINQ program displays the following message as it initiates the complation of 
the DMINTERPRBTER library: 

# GENERATING DMINTERPRETER 
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Remote Generation Using the NOZIP Option 

You can elect to run BUILDINQ but inhibit the ZIP option by entering $NOZIP at the 
prompt for a database name. Use the NOZIP option when you want to set any of the 
following: 

• Class specification 

• Family specification 

• Usercode specification 

• Fetch specification 

• Job attribute assignment 

Selecting the NOZIP Option 

The procedure for setting NOZIP is identical to the procedure for generating a 
DMINTERPRETER library with the ZIP option, with the following exceptions: 

• You must respond twice to the WHAT DATABASE prompt: once to inhibit ZIP and 
once to name the database. 

• When NOZIP is used, BUILDINQ does not prompt you for a queue; the default 
system queue is always used. 

• BUILDINQ does not compile the DMINTERPRETER library; you must use a WFL 
job deck to compile the library. 

The first prompt after you initiate the BUILDINQ program requests the name of the 
database. To inhibit Zn> enter $NOZIP. When the BUILDINQ program reprompts for 
the database name, enter the name of the database. 

You begin the sequence by entering 

R BUILDINQ 

The rest of the sequence is as follows: 

BUILDINQ Prompt Your Entry 

WHAT DATABASE? $NOZIP 

WHAT DATABASE? <database name> 

BUILDINQ continues by requesting the view of the database. (See ''Step 3. Selecting a 
Wiew of the Database," in this appendix.) 

Figure A-5 shows the flow of steps wh^ you use the NOZIP option. 
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Initiate 
BUILINQ 



(See step 1} 



Enter 
$NOZIP 



> (See step 2) 



Enter database 
name 



(As required) 



L_ ^ I 



Select database 
name' for 
DMINTERPRETER/<database name> 



(See step 8) 



BUILINQ 
ends 



Run 
WFL deck 



Figure Using the BUILDINQ Program with the NOZIP Option 



Compiling a DIVIINTERPRETER Library Wliere NOZIP Is Set 

The BUIIJDmQ program <aimot compfle a DMINTEKPEETER Kbi^ 

NOZIP option is set; therefore BUILDINQ does not display a request for the compilation 



A-14 



8600 0155-000 



Generating the DMINTERPRETER Library 



queue. Instead, after you enter the database name for the DMINTERPRETER code file, 
BUILDINQ successfully terminates. 

To compile a DMINTERPRETER library with the NOZIP option, you must use a WFL 
job deck that includes the following cards. Do not include a QUEUE statement; any 
queue information is ignored. 

COMPILE DMINTERPRETER/<database name> 

WITH DMAL60L LIBRARY; 
COMPILER FILE TAPE = DATABASE/DMINTERPRETER; 
COMPILER FILE DASDL = DMIDIRECTORY/<database name>; 
COMPILER FILE PROPERTIES = DATABASE/PROPERTIES; 

? DATA 

$ MERGE 

? END 

Note: The file-equation cards might require modification, depending on the 
location of the files being used. 

Generating the DMINTERPRETER Library from WFL 
Job Decks 

BUILDINQ can also be nm entirely using a WFL job deck. The cards listed in Table A-2 
can appear, in any order, in the WFL job. 



Table Ar-2. WFL Cards Used to Generate a DMINTERPRETER Library 



Card 


Action 


DATABASE : <database name> 


If this card is present, the database description file is 
found in a file titled DESCRIPTION/<database 
name>. BUILDINQ produces the DMIDIRECTORY but 
does not begin compilation of DMINTERPRETER. 

If this card is not present, the DASDL source file must 
be label-equated to the title of the database 
description file. 


DMINTERPRETER 


This card must be present to specify the 
DMINTERPRETER. 


LDBNAME : <database iiaine> 


If this card is present, access to the specified k^icat 
datat}ase is assumed; otherwise, access to the total 
database is assumed. The <database name> must 
refer to a logical database declared in D^DL 


QUEUE : <iiiteger> 


If this card is present, DMII^ERPRETER is compiled 
In the specified queue; otherwise, it is compiled in the 
system defoult queue. 


continued 
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Table A-2. WFL Cards Used to Generate a DMINTERPRETER Library (cont.) 



Card 


Action 


NOUPDATE 


If this card is present, records cannot be updated. 




There is no ability to create, delete, or update records; 




vou onlv can inouirs If this card is not oresent 




records can be created, deleted, and updated, and you 




also can inquire. 




Note: Ifyou compile a DMINTERPRETER 




library with an INQUIRY only access, 




any attempt by a program to open a 




database with an OPEN UPDATE 




command results in an UNKNOWN 




OPEN TYPE error. Attempts to 




create, delete, or update records result 




in READONLY errors. 



The CARD input ffle for BUILDINQ can be made into a ffle of type DISK, REMOTE, or 
READER. 



If the WFL compiler encoimters an an error when nmnii^ the BUILDINQ job deck, 
WFL displays the appropriate error message and terminates BUILDINQ 'without 
completing the job. 

Considt the Task Attributes Reference Manual, the Task Management Guide, and the 
WFL Reference Manual for more information about WFL and WFL job de(dcs. 

The following three examples show how to use these cards in a WFL job deck. 
Example 1: Basic Implementation 

In the first WFL job, the DATABASE card specifies the database (MYDB) whose 
descrq>tion file is used to build DMINTERPRETER. DMINTERPRETER is compiled 
from queue 40. 

?BEGIN JOB BUILDINQFROMCARDS; 

RUN OBJECT/BUI LDINQ; 

DATA 

DATABASE : MYDB 
DMINTERPRETER 
QUEUE : 40 
?END JOB. 
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Example 2: Using a File Equation 

The second WFL job iises a file equation to give the external name of the DASDL 
file (DESCRIPTION/MYDB) for the database whose description file is used to build 
DMINTEItPKETEB. Again, DMINTERPRETER is compiled from queue 40. 

7BEGIN JOB BUILDINQFROMCARDS; 

RUN OBJECT/BUILDINQ; 

FILE DASDL (TITLE=DESCRIPTION/MYDB) ; 

DATA 

DMINTERPRETER 
QUEUE : 40 
?END JOB 

Example 3: Grenerating in a Batch Environment 

The third WLF job shows how the interpretive interface can be generated in a batch 
environment for a database named DMIDB. 

?BEGIN JOB CREATE/DMINTERPRETER; 
TASK T; 

REMOVE DMIDIRECTORY/DMIDB; 
RUN OBJECT/BUILDINQ [T] ; 
DATA 
$NOZIP 

DATABASE : DMIDB 
DMINTERPRETER 

? % END BUILDINQ INPUT — 

IF T ISNT COMPLETEDOK THEN 
ABORT "BUILDINQ RUN FAILED"; 

COMPILE DMINTERPRETER/DMIDB WITH DMALGOL [T] LIBRARY; 
COMPILER FILE DASDL (TITLE=DMIDIRECTORY/DMIDB) ; 
COMPILER FILE CARD (KIND=PACK, 

TITLE=DATABASE/DMINTERPRETER) ; 
IF T ISNT COMPILEDOK THEN 
ABORT "DMINTERPRETER COMPILE FAILED"; 
?END JOB. 
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Appendix B 

DMSII Exceptions and Errors 



The Accessroutines returns exception and error messages to an application program 
when data management operations cannot be successfully or correctly completed. 

• Exceptions are caused by problems within the application program. For example, an 
exception is returned if your application program tries to nest logical transactions. 

• Errors are caused by problems within the database or DMSII software. For 
instance, an error is returned if there is an invalid index within the DMSII code. 

Many responses to error messages require nmning DMSII utilities such as 
REORGANIZATION, DECERTIFICATION, DMUTILn% and REBUILD. For details 
about the DMSII utilities, consult the DMSII Utilities Operations Guide. Some 
responses require changes to the DASDL source file for your database. For in-depth 
information on DASDL, read the DMSII DASDL Reference Manual. 
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Categorizing Exceptions and Errors 

The exceptions and errors are divided into 21 msgor categories. Each major category has 
an associated category number and mnemonic. For example, the major category known 
by the mnemonic SYSTEMERROR is also knovm as major category 7. Table B-1 lists 
the numbers and mnemonics for the major categories by category number, in ascending 
order. 



Table B-1. Major Categories for Exceptions and Errors by Category Number 



Number 


Mnemonic 


Number 


Mnemonic 


1 


NOTFOUND 


11 


OPENERROR 


2 


DUPLICATES 


12 


CLOSEERROR 


3 


DEADLOCK 


13 


NORECORD 


4 


DATAERROR 


14 


INUSE 


5 


NOTLOCKED 


15 


AUDITERROR 


6 


KEYCHANGED 


16 


ABORT 


7 


SYSTEMERROR 


17 


SECURITYERROR 


8 


READONLY 


18 


VERSIONERROR 


9 


lOERROR 


19 


FATALERROR 


10 


LIMITERROR 


20 


INTEGRITYERROR 






21 


INTLIBERROR 



Note: Any message that can be returned through the language extensions 
can be returned through the interpretive interface. However, 
INTLIBERROR (category 21) messages can be returned only to 
application programs using the interpretive interface. 

Within each major category, each cause for the exception or error is a subcategory. Every 
subcategory has an associated subcategory ntunber. Tables B-2 through B-21 list the 
major categories alphabetically by mnemonic. Under each categoiy, the table lists the 
valid subcategories and their meaning. 

ABORT Category 

The ABORT categoiy is also known as major category 16. The most probable cause for 
an ABORT message is a database ab(n*t or a rollback. 

Table B-2 lists the esxseptions and errors subcategories associated with an ABORT 
message. 
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Table B-2. ABORT Subcategories 


Subcategory 




Number 


Meaning 


1 


The database was aborted and rolled back. 


2 


An abort occurred, and the Transaction Processing System (TPS) rerun was not 




finished. 



AUDITERROR Category 

The AUDITERROR category is also known as major category 15. The most probable 
cause for an AUDITERROR messs^e is a conflict in transaction state. 

Table B-3 lists the exceptions and errors subcategories associated with an 
AUIDTERROR message. 



Table B-3. AUDITERROR Subcategories 



Subcategory 
Number 


Meaning 


1 


The program attempted to execute a begin transaction operation on a database 
that is already in transaction state. 


2 


The prc^ram attempted to execute an end transaction operation on a database that 
is not in transaction state. 


3 


The program attempted to execute a MIDTRANSACTION statement on a database 
that is not in transaction state. 


4 


The program attempted to execute a nonnal b^in or end transaction operation on 
a database that was opened by TPS. 


5 


The program attempted to execute a TPS b^in transaction or end transaction 
operation on a database that was not opened by TPS. 


6 


The transaction record has an improper TRSTATE value. 


7 


The program attempted to execute a MIDTRANSACTION statement on a database 
that was not opened by TPS. 


8 


The program attempted to update an audited database when the program was not 
in transaction state. 


9 


The program attempted to abort a single transaction when the program was not in 
transaction state. 


10 


The program attempted to write a savepoint record when the prc^ram was not in 
transaction state. 
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Table B-3. AUDITERROR Subcategories (cont.) 


Subcategory 
Number 


Meaning 


11 


The program attempted either to abort a single transaction or to write a savepoint 
record, but the DASDL option INDEPENDENTTRANS was not set for the database. 



CLOSEERROR Category 

The CLOSEEREOR category is also known as major category 12. The most probable 
cause for a CLOSEERROR message is an error in dosing the database. 

Table B-4 lists the exceptions and errors subcategories associated with a CLOSEERROR 
message. 



Table B-4. CLOSEERROR Subcategories 


Subcategory 




Number 


Meaning 


1 


The database is not open. 


2 


An Accessroutines error occurred on one or more structures. 



DATAERROR Category 

The DATAERROR categoiy is also known as major category 4. The most probable cause 
for a DATAERROR message is a null value in a required item. 

Table B-5 lists the exceptions and errors subcategories associated with a DATAERROR 
messs^. 



Table B-5. DATAERROR Subcategories 



Subcat^ry 




Number 


IMeaning 


1 


Either some required Items are null, or tiie VERIFY condition failed. (The divisor of 




an aggregate item must not be zero.) 


2 


The program attempted to create variable-fomriat records with an invalid value for 




the record type. 



continued 
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Table B-5. DATAERROR Subcategories (cont.) 


Subcategory 




Number 


Meaning 


3 


The partition variable yielded an ill^al file identifier. 


4 


READONLY items were changed and now cannot be stored. 


5 


The divisor of a virtual item was 0 (zero). (This condition is data dependent.) 



DEADLOCK Category 

The DEADLOCK category is also known as major category 3. The most probable cause 
for a DEADLOCK message is either a deadly embrace or deadlock condition. 

Table B-6 lists the exceptions and errors subcategories associated with a DEADLOCK 
message. 



Table B-6. DEADLOCK Subcategories 



Subcategory 




Number 


Meaning 


1 


A deadly embrace occun'ed when the program attempted to lock a record or while 




the pr(%ram was waiting for a ti^in transaction operation. 




The system automatically frees all records for this program. 


2 


A timeout occurred when the program attempted to lock a record or while the 




program was waiting for a b^in transaction operation. 


3 


The LOCKLIMIT value was exceeded. Too many records in this database are 




currently locked. 



DUPLICATES Category 

The DUPLICATES categoxy is also known as major category 2. This category usua% is 
reported when duplicates are not allowed. 

Table B-7 lists the exceptions and errors subcategories associated with a DUPLICATES 
message. 
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Table B-7. DUPLICATES Subcategories 



Subcategory 




Number 


Meaning 


1 


Hie program attempted to store a duplicate key item in an index set in which 




duplicates are not allowed. 


2 


The prc^ram attempted to insert a duplicate key item in a subset or data set in 




which duplicates are not allowed. 



FATALERROR Category 

The FATALERROR category is also known as msgor category 19. The most probable 
cause for a FATALERROR message is a fatal error in the Accessroutines. No exception 
subcategories are returned for large systems. 

INTEGRITYERROR Category 

The INTEGRITYERROR category is also known as magor category 20. The most 
probable cause for an INTEGRITYERROR message is an internal structure problem in 
the database. 

Table B-8 lists the ^ceptions and errors subcategories associated with an 
INTEGRITYERROR message. < 



Table B-8. INTEGRITYERROR Subcat^ories 



Subcategory 




Number 


Meaning 


1 


The key and the data do not match. 


2 


The prc^ram attempted to store a record in a missing automatic set or subset. 


3 


The program attempted to delete a record in a missing automatic set or subset. 


4 


An automatic set or subset is pointir^ to a deleted record. 


5 


The program attempted to allocate more than 1000 raws in a file. 



INTLIBERROR Category 

The INTUBEKROR category is also known as magor category 21. This category relates 
only to receptions and errors generated wh^ the interpretive inter&ce is used 
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Table B-9 lists the exceptions and errors subcategories associated with an 
INTLIBEKKOR message. 



Table B-9. INTLIBERROR Subcategories 



Subcategory 
Number 


Meaning 


1 


The first parameter of tiie entry point DBVERB or DBDATA is not a valid language 
extension verb. 


2 


The specified string parameter is not a valid l(eyword. 


3 


The specified structure is not tlie correct stmcture type. 


4 


The structure or link name is not a known database identifier. 


5 


The prc^ram gave conflicting or insufficient qualification for the structure or link 
name. 


6 


The item name is not a database identifier. 


7 


The item type does not correspond to the requested data type. 


8 


The specified item is not in the specified structure. 


9 


The program gave an invalid index for an OCCURS item. 


10 


The program gave an incorrect number of subscripts for an OCCURS item. 


11 


Either the specified item is not in the current variable record type, or the program 
specified an incorrect record-type syntax. 


12 


The program placed a negative value in an unsigned Item. 


13 


The program attempted a get operation for this item and found that the value was 
null. 


14 


The string parameter in a putstring operation is not the same length as the item. 


15 


The structure or link name is invalid. 


16 


The item name is invalid. 


17 


A selection expression contains an invalid literal. 


18 


A right parenthesis is missing in the selection ^pression. 


19 


A relational operator is expected in the selection expression. 


20 


In a selection expression, either a relational operator spedfied a null value for a 
required item, or the relational operator was neither EQU (equal to) nor GEQ 
(greater than or equal to). 


21 


Either the selection expression did not end conectly, or some unknown error 
occurred. 


22 


A numeric argument to a put operation is invalid for the item. 


23 


This operation is not valid for global data. 
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Table B-9. INTLIBERROR Subcategories (cont.) 



Subcategory 
Number 


Meaning 


24 


In a selection expression, an item and a literal have either a mismatched length or 
type. 


25 


More than 47 relations appear in a selection expression. 


26 


No valid set spans the embedded data set. 


27 


A software failure occurred in a selection expression tree execution. 


28 


The prc^ram attempted to execute an invalid request while the database was 
closed. 


29 


The program attempted to execute a store or delete operation when the program 
was not in transaction state. 


30 


An index set was left undefined by a data set condition search. 


31 


The parameter is too short to hold the responsis. 


32 


The value of a number item does not fit into a real parameter. 


33 


The LIMITTYPE parameter is invalid. 


34 


The LIMITVALUE parameter is invalid. 


35 


The FINDLIMIT value was exceeded. 



I NUSE Category 

The INUSE category is also known as major category 14. The most probable cause for 
an INUSE messages is a problem vnth a master record that has embedded records. 

Table B-10 lists the ezcqptions and errors subcategories associated vdth an INUSE 
message. 



Table B-10. INUSE Subcat^ories 


Subcat^jory 




Number 


Meaning 


1 


The program attempted to delete a record without setting its reference and 




embedded set to null. 


2 


The prc^ram attempted to delete a record when the count item was not zero. 


3 


The program attempted to delete a record that has a nonnull embedded structure. 
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lOERROR Category 

The lOEEROR category is also known as major category 9. The most probable cause for 
an lOEKROR message is an input or output error. 

Table B-11 lists the exceptions and errors subcategories associated with an lOEBROB 
message. 



Table B-11. lOERROR Subcategories 



Subcategory 
Number 


Meaning 


1 


The unit is not ready. 


2 


A read parity error occurred. 


4 


A descriptor error occurred. 


5 


Tlie Accessroutines encountered a NO SPACE condition. This type of exception can 
occur under the following conditions: 

• A DMSII data file is contained on a multipack family. 

• One of the packs of the multipack family is re-created. 

• M program anempieo a uivioii operaiion involving a recoru on ine newiy 
re-created pack. 


6 


The program attempted to read past the end of the file. 


7 


The pr(%ram attempted to read or write past the end of the last row. 


8 


The I/O was canceled. 


11 


A pack write-lockout occurred. 


12 


A multiplexor or controller error occumed. 


13 


The pack drive failed . 


14 


A pack sector format error occurred. 


15 


A storage unit timeout occuned. 


16 


A row was locked out because of a previous write error. 


17 


The checksum operation failed. 


99 


An error was generated by an unknown cause. 


256 


The ADDRESSCHECK operation failed. 



KEYCHANGED Category 

The KEYCHANGED category is also known as major category 6. The most probable 
cause for a KEYCEIAN6ED message is a diax^e to a key item when no duplicates are 
allowed. 
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Table B-12 lists the exceptions and errors subcategory associated y/ith a KEYCHANGED 



message. 






Table B-12. KEYCHANGED Subcategories 


Subcategory 




Number 


Meaning 


1 


The program attempted to change the key item of a set or automatic subset that 




does not allow duplicate keys. 



LIMITERROR Category 

The LIMITERROR category is also known as major category 10. The most probable 
cause for a LIMITERROR message is a file reaching its maxImuTn physical limit. 

Table B-13 lists the exceptions and errors subcategories associated with a LIMITERROR 
message. 



Table B-13. LIMITERROR Subcat^ories 


Subcategory 
Number 


Meaning 


1 


The program attempted to store too many records in a structure. 


2 


The program attempted to make too many counted links refer to one record. The 
count list in the DASDL source file was exceeded. 


3 


The program attempted to put too many entries into a set or subset. 


5 


The program attempted to open too many partitions. 


6 


The program referenced a partitioned structure in a DMUTILITY INITIALIZE 
statement. 


7 


There are too many pointers for this structure. 



NORECORD Category 

The NORECORD category is also known as major categozy 13. The most probable cause 
for a NORECORD message is an invalid current path. 

Table B- 14 lists the exceptions and errors subcategories associated \vith a NORECORD 
message. 
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Table B-14. NORECORD Subcategories 



Subcategory 




Number 


Meaning 


1 


The current path of the record to be inserted is not valid. 


2 


The current path of the record to be deleted (removed) is not valid. 


3 


The current path containing the link is not valid. 


4 


The current path of the record to be linked to is not valid. 


5 


The current path of the master record is not valid. 


6 


The current path of the record to be found is not valid. 



NOTFOUND Category 

The NOTFOUND category is also kno\m as major category 1. A NOTFOUND message 
is most likely to be issued when no record that meets the given criteria can be found. 

Table B-15 lists the exceptions and errors subcategories associated with a NOTFOUND 
message. 



Table B-15. NOTFOUND Subcategories 



Subcategory 
Number 


Meaning 


1 


No record satisfies the condition. 


2 


The prc^ram attempted to execute a next operation when the pointer was at the 
last entry in the structure. 


3 


The prc^ram attempted to execute a prior operation when the pointer was at the 
first entry in the structure. 


4 


The manual subset key does not con^espond with the in the data record. 


5 


No current record could be found. 


6 


The current path is undefined. 


7 


Either the master record pointer is undefined, or the embedded structure has not 
been created. 


8 


The link is undefined. 


9 


The link does not agree with the data record. 
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Table B-15. NOTFOUND Subcategories (cont.) 



Subcategory 




Number 


Meaning 


10 


The link does not exist in the current record. (The program specified the wrong 




type of variable^ormat record.) 


11 


A select-text error occurred . 


12 


An invalid index resulted from an OCCURS clause. 



NOTLOCKED Category 

The NOTLOCKED category is also known as major category 5. A NOTLOCKED 
message is most likely to be issued when a store operation is not preceded by a create or 
modify operation. 

Table B-16 lists the exceptions and errors subcategories associated with a NOTLOCKED 
message. 



Table B-16. NOTLOCKED Subcategories 



Subcategory 




Number 


Meaning 


1 


The program attempted to execute a store operation without first performing either 




a create operation, a lock and modify operation, or a store operation. 


2 


The program attempted to modify an unlocked record. 



OPENERROR Category 

The OPENEBEOR category is also known as major category 11. The most probable 
cause for an OPENEBEOR message is an error in opening the database. 

Table B-17 lists the exceptions and errors subcategories associated with an 
OPENERROR message. 
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Table B-17. OPENERROR Subcategories 



Subcategory 
Number 


Meaning 


1 


The AccessroLitines is not present on disk. 


2 


An I/O error occurred in the Accessroutines code file. 


4 


The DMUTILITY program tried to initialize when the database was in use. 


5 


The run-time description of the datat)ase does not match the compiie-time 
description. 


6 


An Accessroutines error occuned on one or more structures. 


7 


The description files for the application prc^ram and the DMSUPPORT library were 
compiled with different timestamps. 


9 


The program attempted to open RECOVERY, but RECOVERY was not necessary. 


10 


The program discontinued when the restart data set was opened. 


11 


A read error occurred on segment 0 of the restart data set. 


12 


The Drosram discontinued when initiaiizin? the restart data set to emotv 


1 


1 1 Ic piUgidlll UlovAJIIUllUcU Wllcil Ullailglllg Ulc ilaiilco Ol Ulc IcbLdfl Udla ocL. 


14 


The restart data set is not present. 


15 


The program attempted to open RECOVERY, but RECOVERY was already In 
progress. 


16 


A required structure was not invoked. 


17 


An invoked structure was not found. 


18 


The program attempted to open RECONSTRUCTION when RECONSTRUCTION 
was already in progress. 


19 


The reconstruction was unsuccessful. 


20 


The DBS stack overflowed. 


23 


The program attempted to initialize one or more partitions when the partitions 
already existed. 


24 


The program discontinued because a file attribute en^or occurred when the program 
attempted to open a file. 


25 


The program attempted to open a logical database that did not exi^. 


26 


The program received a security error when attempting to execute an open 
operation. 
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( 



Table B--17. OPENERROR Subcategories (cont.) 



Subcategory 
Number 


Meaning 


27 


The Accessroutines code file is not tine same as the code file used by the database. 

If the Accessroutines is copied while the database is open, any subsequent 
prc^ram that opens the database also receives this error until the database is 
dosed. 

Either specify the correct Accessroutines title in the DASDL source file, or remove 
the incorrect copy from the usercode and family of the program that opened the 
Qaiaoase. 


28 


Thp ^votpm iin^hlp tn rpprl rnw f) nf thp rpof^rt tipiff^ cpt Pun thp 

RECONSTRUCT program. 


29 


The prc^ram was compiled with a description file that has a higher update level 
than the description file used to compile the DMSUPPORT library. 


31 


An I/O error occurred in the control file. 


32 


The prc^ram attempted to execute an unknown type of open operation. 


33 


The database was open when a hall/load occurred. 


34 


The audit trail could not be initialized. 


35 


There is insufficient memory for the DBS stack. 


36 


The Accessroutines code file is unacceptable. 


37 


An open error occurred in the control file. 


38 


The database software does not match the format for the structure. 


39 


The control file is locked by an exclusive function. 


40 


The application program must be recompiled on a more recent release. 


41 


The program and the DMSUPPORT library are compiled with different description 
files. 


A A 

44 


The DBS is not visible from the sut)system for the program. 


45 


This option is not permitted while TPS is active. 


46 


This option is not pennitted until the TPS RECOVERY program is complete. 


47 


The initiation of the Accessroutines failed. 


48 


The application program discontinued before the Accessroutines was frozen. 


49 


The control file is not present on disk. 


50 


The program received an VO error while reading block 0 of the control file. 


56 


The Accessroutines code file does not support audit. 
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Table B-17. OPENERROR Subcategories (cont.) 



Subcategory 
Number 


Meaning 


57 


The Accessroutines code file do^ not support partitions. 


58 


The Accessroutines code file does not support local buffering. 


oy 


1 ne program auempieu lo open a □aiauase inai is aireaay in use oy an exclusive 
or single update user. 


60 


The program attempted to either open a database exclusively or make a database a 
single update datafc)ase when the database Is already In use by another prc^ram. 


61 


The program attempted to open a Semantic Information Manager (SIM) database, 
but SIM has not been Implemented on the system. 


62 


The program attempted to update a SIM database that can be accessed only for 
inquiry purposes. 


CO 


The prc^ram attempted to update a DMSII database that can be accessed only for 
inquiry purposes. 


64 


The pr(%ram attempted to library-equate a new DMSUPPORT library, but either 
there is an existing DMSUPPORT library or the old DMSUPPORT library Is still 
being accessed. 


65 


The usercode under which the database control file is stored is not a valid 
usercode for the system. 

Either make the usercode a valid system usercode, or move the control file to an 
existing valid system usercode. 


66 


The DMSUPPORT library is not resident. 


67 


The DMSUPPORT library needs to be recompiled. 


68 


The Absolute Block Serial Number (ABSN) Is approaching its maximum allowable 
value and must be reset. (For information on resetting the ABSN, refer to the 
DMSn Utilities Operations Guide.) 


69 


A rebuild or rollback procedure is in progress. 


70 


The chaige code for the database owner is no longer valid. 



READONLY Category 

The READONLY category is also known as major categoxy 8. The most probable cause 
for a BEADONLY message is an attempt to alter a record when the database is open for 
inqxairy only. 

Table B-18 lists the exceptions and errors subcategories associated with a BEADONLY 
message. 
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Table B-18. READONLY Subcat^ories 



Subcategory 




Number 


Meaning 


1 


The program attempted to change the database while in the inquiry access mode. 


2 


The program attempted an insert or remove operation on a READONLY record. 


3 


The program attempted a create operation for a new partition while in inquiry 




mode. 



SECURiTYERROR Category 

The SECURTTYEKROR category is also known as major category 17. The most probable 
cause for a SECURTTYEItEtOR message is a violation of system security. 

Table B-19 lists the exceptions and errors subcategory associated with a 
SECURITYERROR message. 



Table &-19. SECURITYERROR Subcategories 


Subcat^ory 
Number 


Meaning 


1 


Verb security: either the program or the user is not pennitted to use this function. 



SYSTEMERROR Category 

The SYSTEMERROR category is abo known as major category 7. The most probable 
cause for a SYSTEMERROR message is an invalid structure numb^. 

Table B-20 lists the exceptions and errors subcategories associated with a 
SYSTEMERROR message. 



Table B-20. SYSTEMERROR Subcat^ories 



Subcat^ry 




Number 


Meaning 


1 


The prc^ram attempted a find first, next, prior, or last operation on an embedded 




standard or compact data set. 


2 


A generate operation is not allowed on this type of set. 
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Table B-20. SYSTEMERROR Subcategories (cont.) 



Subcategory 
Number Meaning 

3 The system attempted to read beyond the end of the file. 

4 An Accessroutines fault occurred during a DMSFREE operation. 

5 An invalid calling sequence or other sequence of events occurred. 

6 A fatal software error occurred. A fatal software error Is produced In the following 
situations: 

• Internal system locks are used inconsistently. 

• Linkage between blocks of data Is inconsistent. 

• Information read from a mass storage device is inconsistent with information 
requested. 

7 A fatal integrity error occurred. A fatal int^rity error is produced in the following 
situations: 

• An address of 0 (zero) is encountered. 

• A block address is not on a block boundary. 

• A record address Is not on a record boundary. 

• The value of a key item in a set or subset does not match the value in a data 
set. 

• A set or an automatic subset points to a deleted record. 

• A record does not have an entry in a set or an automatic subset when it 
should have such an entry. 

8 A fatal i/0 enx)r occurred. A fatal I/O en^r occurs in the following situations: 

• The audit file cannot be opened. 

• Recovery information cannot be read or written. 

• The Accessroutines encountered I/O errors when attempting to allocate or 
deallocate file available space. 

9 A fatal resource error occurred. A fatal resource error is encountered in the 
following situations: 

• The main memory is exhausted. 

• There is not enough space in the restart data set. 

10 A fatal unknown error occurred. This error occurs when abort recovery tenninates 
on an en^r. 
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Table B-20. SYSTEMERROR Subcategories (cont.) 



Subcategory 
Number 


Meaning 


11 


A fatal operator discontinue database error occun^d. This error occurs in the 
Toiiowing siiuaiions: 

• A program attempted to open a database just after the operator discontinued 
the database. 

• The database is being terminated due to some fetal error. . 


12 


A software error occurred in the control file handler. 


13 


The partitions control in the control file are not initialized. 


14 


The Accessroutines code file is compiled without this structure type. 


15 


An error occumed while the system was executing an internal SIM remap and test 
procedure. 



VERSIONERROR Category 

The VERSIONEKROE category is also known as megor category 18. The most probable 
cause for a VEBSIONEBROR message is a program-to-database mismatch. 

Table B-21 lists the exceptions and errors subcategories associated vdth a 
VERSIONERROB message. 



Table B-21. VERSIONERROR Subcategories 



Subcategory 




Number 


Meaning 


1 


The link is unknown or was deleted. 


2 


The program attempted to reference a structure that has been deleted or changed 




since the program was compiled. 
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Summarizing the Relationship of Data Management 
Operations to Exceptions and Errors 

Figure B-1 siumnarizes the data management operations that can cause each exception 
and error subcategory. 

Notes: 

• Exception categories and subcategories resulting from a close 
operation are valid, whether or not the eoxeption branch is 
taken. 

• No DMSn data management operation produces a 
FATALERROR exception. 

• Any entry point in the DMINTERPRETER library can cause an 
INTLIBERROR exception. 

• The specified LIMITERROR exceptions apply only when the file 
size is eoxeeded. Any operation which causes a new partition 

to be opened implicitly can cause a limiterror. The close, begin 
transaction, and end transaction operations are the only 
operations that cannot produce a UMITERROR exception. 

• A test link for null can result in a VERSIONERROR if the link 
was deleted using the REORGANIZATION program. 
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V ERRORS AND 
EXCEPTIONS 

OPERATION \^ 


ABORT 1 


AUDI TERROR 


CLOSEERROR | 


DATAERROR | 


DEADLOCK | 


DUPLICATES 


FATALERROR ( 


INTEGRITY ERROR 


INTLIBERROR 


INUSE 


lOERROR 


KEYCHANGE 


LIMITERROR | 


NORECORD 1 


NOTFOUND 1 


NOTLOCKED | 


OPENERROR 


READONLY | 


SECURITYERROR | 


SYSTEMERROR 


VERSIONERROR { 


ABORTTRANSACTION 
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j Any entry point in OMINTERPRETER can cause this error. 
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Figure B-1. Relationship of Data Management Operations to Errors and Exceptions 
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Appendix C 

Sample Programs That Use the 
Interpretive Interface 



The ALGOL, COBOL74, and FORTRAN?? application programs shown in this appendix 
use the DMSn interpretive interface to create, store, retrieve, delete, and re-create 
various data items of differing types. 

All the programs use the same database. The DASDL description of the database is 
presented first, followed by the programs. 
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DASDL Database for Sample Programs 



DASDL Database for Sample Programs 

The follo^vixig DASDL code creates £MP JOB, the database that is accessed all the 
sample application programs provided in this appendix. 

EMP JOB contains a restart data set, a global record, and three data sets: EME^ JOB, 
and ADR. 

• The EMP data set has an embedded data set (EMP-ED), three sets 
(EMP-DATE-SET, EMP-NO-SET and EMP-LNAME-SET), and an automatic subset 
(EMP-OVERIO-SUBSET). 

• The JOB data set is a variable format data set with two record types. The JOB data 
set has a set (JOB-CODE-SET), an automatic subset (JOB-MNG-SUBSET), and an 
embedded, manual subset (JOB-EMP-SUBSET). 

• The ADB data set has one set, ADR-ZIP-SET. 

For details on DASDL, read the DMSII DASDL Programming Reference Manual. For 
database design techniques, read the DMSII Technical Overview. 
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DASDL Database for Sample Programs (cont.) 



RSTART RESTART DATA SET 
(ALPHAID ALPHA (7)); 



GLOBAL RECORD 



FISCAL-YEAR "NEEDS UPDATING EVERY YEAR" NUMBER (6); 
POP-EMP POPULATION (50) OF EMP; 
DIV-NUMBER NUMBER (5) ; 

***** £fHp ***** 

EMP DATA SET "MASTER EMPLOYEE FILE" 
POPULATION = 50 
( 

EMP-NO 
EMP-NAME 
^ ( 

^ EMP-LNAME 
^ EMP-FNAME 

^ ); 

EMP-SSN 



NUMBER 
GROUP 

ALPHA 
ALPHA 

NUMBER 

EMP-DATE-HIRED "YYMMDD" NUMBER 
EMP-SEC-CLEAR "T=YES" BOOLEAN 
EMP-SALARY "MONTHLY" NUMBER 

>• EMP -ED ****** 



(4) ; %ACTUAL EMP NUMBER 



(10); 
(10); 



(9) 
(6) 

(6.2) 



EMP-ED DATA SET "EDUCATIONAL RECORDS FOR EACH EMPLOYEE" 

^ POPULATION = 10 
^ ( 

^ ED-DATE "YYMMDD" 

^ ED-INST-NAME 

^ ED-INST-CODE 

^ ED-COURSE 

^ ED-GPA 

^ ); 

ED-DATE-SET 
EMP-JOB-REF 

); 

EMP-NO-SET 
EMP-LNAME-SET 



NUMBER 

ALPHA 

NUMBER 

ALPHA 

NUMBER 



(6); 
(30); 

(4); 

(10); 
(3.2); 



%UNIQUE TO SCHOOL 



^GRADE PT AVR 



SET OF EMP-ED KEY ED-DATE I-S; 
REFERENCE TO JOB COUNTED; 



SET OF EMP KEY EMP-NO I-S; 
SET OF EMP 

KEY EMP-LNAME DUPLICATES I-S; 
EMP-OVER10-SUBSET "VESTED EMPLOYEES" SUBSET OF EMP 

WHERE (EMP-DATE-HIRED < 700000) 
BIT VECTOR; 



JOB 



JOB DATA SET "REC TYPE 1 IS CLERICAL. REC TYPE 2 IS NON-CLERICAL" 

POPUUTION 10 

( 

JOB-COUNT COUNT (10); 

JOB-TYPE TYPE (2) ; 
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DASDL Database for Sample Programs (cont.) 



JOB-CODE 
JOB-TITLE 
JOB-EMP-SUBSET 
). 

1: 

( 

TYPE-SPEED 
SHORTHAND-SPEED 
CRTUSE-REQD 
), 

2: 

( 

SPANISH-REQD 
DRIVING-REQD 
JOB-COMMENT 

); 

JOB-CODE-SET 
JOB-MNG-SUBSET ' 



NUMBER (4) ; 
ALPHA (30) ; 

SUBSET OF EMP KEY EMP-NO; 



NUMBER 
NUMBER 
BOOLEAN 



BOOLEAN 
BOOLEAN 
ALPHA 



(2) 
(2) 



(50) 



SET OF JOB KEY JOB-CODE I-S; 
MANAGERS" SUBSET OF JOB WHERE 
(JOB-CODE > 4999) ; 



ADR 



ADR DATA SET "MASTER ADDRESS FILE" 

POPULATION = 50 

( 

ADR-EMP-NO NUMBER 
ADR-INFO GROUP 
^ ( 

^ ADR-STREET-NO ALPHA 
^ ADR-ZIP NUMBER 

^ ); 
); 

ADR-ZIP-SET 



(4); 



(30); 
(5); 



SET OF ADR KEY ADR-ZIP I-S DUPLICATES; 
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ALGOL Application Program Using the Interpretive Interface 



ALGOL Application Program Using tlie Interpretive 
Interface 

BEGIN 

FILE REMOTEFILE 

(KIND=REMOTE 

,UNITS=CHARACTERS 

,MAXRECSIZE=1920 

,MINRECSIZE=1 

,FILETYPE=3 

); 

$$ INCLUDE DMISYM="DATABASE/DMINTERPRETER" 20100000-20199999 
^*********************************************** 

%* This program uses the ALGOL declaration of library entry points *% 

%* from the DATABASE/DMINTERPRETER symbolic file rather than *% 

%* explicitly declaring each entry point. *% 
^************************************************** 



%* LOCAL DECLARATIONS *% 

REAL 

EXPR_1; 

DOUBLE 

EXPR_2; 

STRING 

DATA_SET_NAME 

,FIRST_1 

,PRI0R_1 

,NEXT_T 

,P_AUDIT 

,OPEN_TYPE 

,BEGIN_1 

,C0NDITI0N_1 

,SPACE_1 

,DATA_BUFFER 

,DATA_REQUEST 

.ITEM_NAME 

,EXPR__3 

.EXCEPTIONMSG; 
BOOLEAN 

RSLT 
.EXPR_4; 
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ALGOL Application Program Using tlie Interpretive Interface (cont.) 



%* INTERNAL PROCEDURE TO HANDLE EXCEPTIONS *% 

^************************************************* 

PROCEDURE EXCEPTIONHANDLER; 

BEGIN 

STRING 

EXCEPTIONMSG; 
BOOLEAN 

STATUS RSLT; 

STATUSRSLT:=DBSTATUS; 

DBEXCEPTIONNAME (STATUSRSLT , EXCEPTIONMSG) ; 
WRITE(REM0TEFILE,<"EXCEPTI0N-NAME=",A14>,EXCEPTI0NMSG) ; 
DBEXCEPTIONTEXT (STATUSRSLT, EXCEPTIONMSG) ; 
WRITE{REMOTEFILE,<"EXCEPTION-TEXT=">) ; 
WRITE(REMOTEFILE,<A60>,EXCEPTIONMSG) ; 
END OF EXCEPTIONHANDLER; 

«^********************************************* 

%* BODY OF MAIN PROGRAM *% 

^*************************************************^ 

DMI.TITLE:="DMINTERPRETER/EMPJOB"; 

DATA_SET_NAME : =" EMP" ; 
FIRST_1:=" FIRST"; 
PRI0R_1:=" PRIOR"; 
NEXT_T:="NEXT"; 
P__AUDIT:=" AUDIT"; 
OPEN_TYPE:="UPDATE"; 
BEGIN_1:="BEGINNING"; 
C0NDITI0N_1 :="EMP-N0=11" ; 
SPACE_1:=" "; 

%* OPENING THE DATABASE *% 



RSLT:=DBOPEN(OPEN_TYPE) ; 
IF RSLT 

THEN EXCEPTIONHANDLER; 
WRITE(REMOTEFILE,<"SUCCESSFUL OPEN OF EMPJOB">); 
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ALGOL Application Program Using the Interpretive Interface (cont.) 



%* DELETING A RECORD *% 

RSLT:=DBBEGINTRANSACTION (P__AUDIT) ; 
IF RSLT 

THEN EXCEPTIONHANDLER; 

RSLT : =DBDELETE (FI RST_1 , DATA__SET_NAME,C0NDITI0N_1) ; 
IF RSLT 

THEN EXCEPTIONHANDLER; 

C0NDITI0N_1:="EMP-N0=12"; 

RSLT:=DBDELETE(FIRST_1 ,DATA_SET_NAME,C0NDITI0N_1) ; 
IF RSLT 

THEN EXCEPTIONHANDLER; 



RSLT:=DBENDTRANSACTION(P_AUDIT) ; 
IF RSLT 

THEN EXCEPTIONHANDLER; 



WRITE (REMOTEFILE. <"SUCCESSFUL DELETE OF RECORD">); 



%* CREATING A RECORD *% 



RSLT:=DBCREATE(DATA_SET_NAME,SPACE_1) ; 
IF RSLT 

THEN EXCEPTIONHANDLER; 

WRITE (REMOTEFILE, <"SUCCESSFUL CREATE OF RECORD">); 




% 

% USING DBPUTREAL ENTRY POINT 



% 

ITEM_NAME:="EMP-NO"; 
EXPR_1:=11; 

rslt7=dbputreal(data_set_name. ITEM_NAME,EXPR_1) ; 

IF RSLT 

THEN EXCEPTIONHANDLER; 



ITEM^NAME: =" EMP-SALARY" ; 
EXPR_1:=4500.95; 

RSLT:=DBPUTREAL(DATA SET_NAME,ITEM_NAME. 2 * EXPR_1); 
if' RSLT 

THEN EXCEPTIONHANDLER; 
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ALGOL Application Program Using tlie Interpretive Interface (cont.) 



% USING DBPUTDOUBLE ENTRY POINT 

% 

ITEM_NAME:="EMP-SSN"; 
EXPR^Z: =573230911; 

RSLT:=DBPUTD0UBLE{DATA_SET_NAME,ITEM_NAME,EXPR_2 - 11 ); 
IF RSLT 

THEN EXCEPTIONHANDLER; 

% 

% USING DBDATA ENTRY POINT 

% 

DATA_REQUEST:="PUT REAL EMP EMP-DATE-HIRED"; 
DATA_BUFFER:="811223" ; 
RSLT:=DBDATA(DATA_REQUEST,DATA_BUFFER) ; 
IF RSLT 

THEN EXCEPTIONHANDLER; 

DATA_REQUEST:="PUT STRING EMP EMP-LNAME"; 
DATA_BUFFER:="STACK" ; 
RSLT:=DBDATA(DATA_REQUEST,DATA_BUFFER); 
IF RSLT 

THEN EXCEPTIONHANDLER; 

% 

% USING DBPUTSTRING ENTRY POINT 

% 

ITEM_NAME:="EMP-FNAME" ; 
EXPR_.3:="CATHY"; 

RSLT:=DBPUTSTRING(DATA_SET_NAME,ITEM_NAME,EXPR_3 CAT "LINA"); 
IF RSLT 

THEN EXCEPTIONHANDLER; 



USING DBPUTBOOLEAN 

ITEM_NAME:="EMP-SEC-CLEAR" ; 
EXPrI4:=TRUE; 

RSLt7=DBPUTB00LEAN(DATA_SET_NAME,ITEM_NAME,N0T EXPR_4) ; 
IF RSLT 

THEN EXCEPTIONHANDLER; 



OS 
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ALGOL Application Program Using the Interpretive Interface (cont.) 



^*************************************************^ 

%* RECORD SETUP IN USER WORK AREA *% 



%* 

%* EMP 
%* NO 

9g* 



EMP 
LNAME 



EMP 
FNAME 



EMP 
SSN 



EMP 
DATE-HIRED 



EMP 
SEC-CLEAR 



EMP 
SALARY 



%*21 STACK CATHYLINA 573230900 811223 FALSE 9001.9 *% 

^****************************************************^ 

%* STORING A RECORD *% 

RSLT:=DBBEGINTRANSACTION(P_AUDIT) ; 
IF RSLT 

THEN EXCEPTIONHANDLER; 

RSLT : =DBSTORE (DATA_SET_NAME) ; 
IF RSLT 

THEN EXCEPTIONHANDLER; 

RSLT:=DBENDTRANSACTION(P_AUDIT); 
IF RSLT 

THEN EXCEPTIONHANDLER; 

WRITE(REMOTEFILE, <"SUCCESSFUL STORE OF RECORD">) ; 



RE-CREATING A RECORD 



RSLT:=DBRECREATE(DATA_SET_NAME,SPACEJ) ; 
IF RSLT 

THEN EXCEPTIONHANDLER; 

WRITE (REMOTEFILE, <"SUCCESSFUL RECREATE OF RECORD">); 

ITEM_NAME:=s"EMP-NO"; 
EXPrIi:=12; 

RSLT:=DBPUTREAL(DATA_SET_NAME,ITEM_NAME,EXPR__1); 
IF RSLT 

THEN EXCEPTIONHANDLER; 

ITEM_NAME:="EMP-SSN"; 
EXPR^a: =549927328; 

RSLtT=DBPUTD0UBLE(DATA_SET_NAME,ITEM_NAME,EXPR_2 - 11 ); 
IF RSLT 

THEN EXCEPTIONHANDLER; 
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ALGOL Application Program Using tiie Interpretive Interface (cont.) 



DATA_REQUEST:="PUT REAL EMP EMP-DATE-HIRED" ; 
DATA_BUFFER:="811228" ; 
RSLT:=DBDATA(DATA_REQUEST,DATA BUFFER); 
IF RSLT 

THEN EXCEPTIONHANDLER; 

DATA_REQUEST:="PUT STRING EMP EMP-LNAME"; 
DATA_BUFFER:="WOLVERTON" ; 
RS LtT=DBDATA (DATA_REQUEST , DATA^BU FFER) ; 
IF RSLT 

THEN EXCEPTIONHANDLER; 

ITEM_NAME:="EMP-FNAME" ; 
EXPR_3:="LAURA"; 

RSLT:=DBPUTSTRING(DATA_SET_NAME,ITEM_NAME,EXPR_3 cat "JANE" ); 
IF RSLT 

THEN EXCEPTIONHANDLER; 

RSLT: =DBBEGINTRANSACTI0N (PLAUDIT); 
IF RSLT 

THEN EXCEPTIONHANDLER; 

RSLT:=DBSTORE(DATA_SET_NAME) ; 
IF RSLT 

THEN EXCEPTIONHANDLER; 

RSLT:=DBENDTRANSACTION (P_AUDIT) ; 
IF RSLT 

THEN EXCEPTIONHANDLER; 

WRITE (REMOTEFILE, <"SUCCESSFUL STORE OF RE-CREATED RECORD">); 



%* SETUP OF RE-CREATED RECORD IN USER WORK AREA *% 




RS LT : =DBSET (DATA_SET_NAME , BEGIN_1) ; 
IF RSLT 

THEN EXCEPTIONHANDLER; 



WRITE (REMOTEFILE, <"SUCCESSFUL DBSET OF DATA SET">); 
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ALGOL Application Program Using the Interpretive Interface (cont.) 



FINDING A RECORD 



RSLT : =DBFIND (FI RST_1 . DATA_SET_NAME,C0NDITI0N_1) ; 
IF RSLT 

THEN EXCEPTIONHANDLER; 

WRITE (REMOTEFILE, <"SUCCESSFUL FIND OF RECORD ">) ; 

%* LOCKING A RECORD *% 

RSLT: =DBLOCK(FI RST_1 , DATA_SET_NAME,C0NDITI0N_1) ; 
IF RSLT 

THEN EXCEPTIONHANDLER; 

WRITE (REMOTEFILE, <"SUCCESSFUL LOCK OF RECORD ">) ; 

5^*****************************************************^ 

%* VERIFYING ITEMS IN THE RECORD *% 



USING DBGETREAL ENTRY POINT 



ITEM_NAME:="EMP-NO"; 

RSLT : =DBGETREAL (DATA_SET_NAME , ITEM_NAME , EXPR__1) ; 
IF RSLT 

THEN EXCEPTIONHANDLER; 
WRITE (REMOTEFILE, <"EMP-N0=",I4>,EXPR 1); 



ITEM_NAME:="EMP_SALARY" ; 

RSLT ; =DBGETREAL (DATA_SET_NAME , ITEM_NAME , EXPR_1) ; 
IF RSLT 
THEN 

WRITE (REMOTEFILE, <"EMP-SALARY=" ,F9.2>,EXPR_1) ; 

% 

% USING OBGETDOUBLE ENTRY POINT 

% 

ITEM_NAME:="EMP-SSN"; 

RSLT : =DBGETDOUBLE (DATA__SET JAME, ITEM^NAME, EXPR_2) ; 
IF RSLT 

THEN EXCEPTIONHANDLER; 
WRITE (REMOTEFI LE , <" EMP-SSN=" . I9>, EXPR_2) ; 
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ALGOL Application Program Using tlie Interpretive Interface (cont.) 



USING DBDATA ENTRY POINT 

DATA_REQUEST:="GET REAL EMP EMP-DATE-HIRED"; 
RSLT:=DBDATA(DATA_REQUEST,DATA__BUFFER) ; 
IF RSLT 

THEN EXCEPTIONHANDLER; 
WRITE(REMOTEFILE, <"EMP-DATE-HIRED=",A6>,DATA_BUFFER) ; 

DATA_REQUEST;="6ET REAL EMP EMP-SALARY"; 
RSLT:=DBDATA(DATA_REQUEST,DATA_BUFFER) ; 
IF RSLT 

THEN EXCEPTIONHANDLER; 
WRITE (REMOTEFILE, <"EMP-SALARY=",A6>,DATA__BUFFER) ; 

DATA_REQUEST:="GET STRING EMP EMP-LNAME"; 
RSLT:=DBDATA(DATA_REQUEST,DATA_BUFFER); 
IF RSLT 

THEN EXCEPTIONHANDLER; 
WRITE (REMOTEFILE, <"EMP-LNAME=",A10>,DATA_BUFFER) ; 



% USING DBGETSTRING ENTRY POINT 

% 

ITEM_NAME: =" EMP-FNAME" ; 

RSLT: =DBGETSTRING (DATA_SET_NAME , ITEM__NAME , EXPR_3) ; 
IF RSLT 

THEN EXCEPTIONHANDLER; 
WRITE (REMOTEFILE, <"EMP-FNAME=" ,A10>,EXPR_3) ; 

% 

% USING DBGETBOOLEAN ENTRY POINT 

% 

ITEM_NAME:="EMP-SEC-CLEAR" ; 

RS LT : =DBGETBOOLEAN (DATA_SET_NAME , ITEM^NAME , EXPR_4) ; 
IF RSLT 

THEN EXCEPTIONHANDLER; 
WRITE(REMOTEFILE, <"EMP-SEC-CLEAR=",L5>,EXPR_4) ; 




RSLT:=DBFREE(DATA_SET_NAME) ; 
IF RSLT 

THEN EXCEPTIONHANDLER: 

WRITE (REMOTEFILE, <"SUCCESSFUL FREEING OF RECORD">); 
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ALGOL Application Program Using the Interpretive Interface (cont.) 



j^*********************************************** 

%* CAUSING AN EXCEPTION *% 

WRITE(REMOTEFILE, <"CAUSING AN EXCEPTION">) ; 

RSLT : =DBSET (DATA_SET_NAME,BEGIN_1) ; 
IF RSLT 

THEN EXCEPTIONHANDLER; 

RSLT:=DBFIND(PRI0R_1,DATA_SET_NAME, SPACER) ; 
IF RSLT 

THEN EXCEPTIONHANDLER; 

% 

%* USING DBVERB *% 



% USING DBVERB ON A SET STATEMENT 

% 

RSLT:=DBVERB("SET EMP TO BEGINNING"); 
IF RSLT 

THEN EXCEPTIONHANDLER 
WRITE(REMOTEFILE,<"SUCCESSFUL SET EMP TO BEGINNING">) ; 

% 

% USING DBVERB ON A SEARCH STATEMENT 

% 

RSLT:=DBVERB("FIND FIRST EMP AT EMP-N0=11"); 
IF RSLT 

THEN EXCEPTIONHANDLER; 
WRITE(REMOTEFILE,<"SUCCESSFUL FIND FIRST EMP AT EMP-N0=11">) ; 

% 

% USING DBVERB ON A STATUS STATEMENT 

% 

RSLT :=DBVERB ("SET EMP TO BEGINNING"); 
IF RSLT 

THEN EXCEPTIONHANDLER; 
DBVERBC'FIND PRIOR EMP "); 

RSLT:=DBVERB("DMSTATUS"); % TO FIND OUT IF THE FIND WAS OK 
DBEXCEPTIONNAME(RSLT, EXCEPTIONMSG) ; 

WRITE (REM0TEFILE,<"EXCEPTI0N-NAME=",A14>,EXCEPTI0NMSG); 
DBEXCEPTIONTEXT (RSLT, EXCEPTIONMSG) ; 
WRITE(REMOTEFILE,<"EXCEPTION-TEXT=">); 
WRITE(REMOTEFILE,<A60>, EXCEPTIONMSG) ; 
WRITE(REMOTEFILE.<"SUCCESSFUL STATUS STATEMENT" >) ; 
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ALGOL Application Program Using the Interpretive Interface (cont.) 



^************************************************^ 



CLOSING THE DATABASE 



RSLT:=DBCLOSE; 
IF RSLT 

THEN EXCEPTIONHANDLER 

WRITE (REMOTEFILE, <"SUCCESSFUL CLOSE OF EMPJOB">); 
END OF DMI EXAMPLE. 



•; 
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C0B0L74 Application Program Using the Interpretive Interface 



C0B0L74 Application Program Using tlie Interpretive 
Interface 

IDENTIFICATION DIVISION. 
************************ 

*PROGRAM-ID. 

*AUTHOR. 

*INSTALLATION. 

*DATE-WRITTEN. 

*DATE-COMPILED. 

*SECURITY. PUBLIC. 

♦REMARKS. 

*THIS PROGRAM USES ENTRY POINTS OF THE DMINTERPRETER LIBRARY 

♦COMPILED FOR THE EMPJOB SAMPLE DATABASE. 
********************* 

ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 



SOURCE-COMPUTER. A 15. 
OBJECT-COMPUTER. A 15. 



INPUT-OUTPUT SECTION. 



FILE-CONTROL. 



SELECT REMOTEFILE ASSIGN TO REMOTE. 




FILE SECTION. 

FD REMOTEFILE 

RECORD CONTAINS 80 CHARACTERS 
VALUE OF TITLE IS "REMOTEFILE". 

01 REMOTE-REC PIC X(80) . 



WORKING-STORAGE SECTION. 
♦DMINTERPRETER CODE FILE. 



01 DMI-NAME PIC X(24) VALUE "DMINTERPRETER/EMPJOB". 

*DMI VOCABULARY. 



01 


DATA-SET-NAME 


PIC 


X(17) VALUE IS "EMP". 


01 


ITEM-NAME 


PIC 


X(17) VALUE IS SPACES. 


01 


FIRST-1 


PIC 


X(5) VALUE "FIRST". 


01 


PRIOR-1 


PIC 


X(5) VALUE "PRIOR". 


01 


NEXT-1 


PIC 


X(4) VALUE "NEXT". 


01 


P-AUDIT 


PIC 


X(5) VALUE "AUDIT". 


01 


N-AUDIT 


PIC 


X{8) VALUE "NOAUDIT". 


01 


OPEN-TYPE 


PIC 


X(6) VALUE "UPDATE". 


01 


BEGIN-1 


PIC 


X(9) VALUE "BEGINNING". 
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C0B0L74 Application Program Using the Interpretive Interface (cont.) 



01 CONDITION-l 

01 SPACE-1 

01 DATA-BUFFER 

01 DATA-REQUEST 

01 VAR-1 



PIC X(9) VALUE "EMP-N0=11", 
PIC X{1) VALUE " 
PIC X(10) VALUE IS SPACES. 
PIC X(40) VALUE IS SPACES. 
PIC X(10) VALUE IS SPACES. 



* EXCEPTION AREA 



01 RESULT 

01 EXCEPTION-NAME 

01 EXCEPTION-MSG 

01 EXCEPTION-WORD 



PIC 9(1) COMP VALUE IS 0. 

PIC X(14). 

PIC X{80). 

PIC 9(12) COMP. 



EXCEPTION-WORD FIELDS 



02 
02 
02 
02 



STRUCTURE 
CATEGORY 
SUB-CATEGORY 
FLAG 



PIC 9(4) COMP. 
PIC 9(3) COMP. 
PIC 9(4) COMP. 
PIC 9(1) COMP. 



******************************************************^ 



PROCEDURE DIVISION. 
MAIN -SECT I ON. 



BODY OF PROGRAM 



LINKING TO DMI LIBRARY 



************************ 



CHANGE ATTRIBUTE TITLE OF "DMINTERPRETER" 
TO DMI -NAME. 



OPEN OUTPUT REMOTEFILE. 



OPENING THE DATABASE 



CALL "DBOPEN OF DMINTERPRETER" 

USING OPEN-TYPE 

GIVING RESULT. 
IF RESULT = 1 

PERFORM EXCEPTION-HANDLER. 
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C0B0L74 Application Program Using tlie Interpretive Interface (cont.) 



DELETING A RECORD 



CALL "DBBE6INTRANSACTI0N OF DMINTERPRETER" 

USING P-AUDIT 

GIVING RESULT. 
IF RESULT = 1 

PERFORM EXCEPTION-HANDLER. 
CALL "DBDELETE OF DMINTERPRETER" 

USING FIRST-1, DATA-SET-NAME, CONDITION-1 

GIVING RESULT. 
IF RESULT = 1 

PERFORM EXCEPTION-HANDLER. 
MOVE "EMP-N0=12" TO CONOITION-1. 
CALL "DBDELETE OF DMINTERPRETER" 

USING FIRST-1, DATA-SET-NAME, CONDITION-1 

GIVING RESULT. 
IF RESULT = 1 

PERFORM EXCEPTION-HANDLER. 
CALL "DBENDTRANSACTION OF DMINTERPRETER" 

USING P-AUDIT 

GIVING RESULT. 
IF RESULT = 1 

PERFORM EXCEPTION-HANDLER. 



* CREATING A RECORD * 

CALL "DBCREATE OF DMINTERPRETER" 

USING DATA-SET-NAME, SPACE-1 

GIVING RESULT. 
IF RESULT =1 

PERFORM EXCEPTION-HANDLER. 



* FILLING IN A RECORD * 

* 



USING DBDATA ENTRY POINT 

MOVE "PUT REAL EMP EMP-NO" TO DATA-REQUEST, 
MOVE "11" TO DATA-BUFFER. 
C^LL "DBDATA OF DMINTERPRETER" 

USING DATA-REQUEST,DATA-BUFFER 

GIVING RESULT. 
IF RESULT = 1 

PERFORM EXCEPTION-HANDLER. 
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C0B0L74 Application Program Using ttie Interpretive Interface (cont.) 



MOVE "PUT REAL EMP EMP-SALARY" TO DATA-REQUEST. 
MOVE "9001.90" TO DATA-BUFFER. 
CALL "DBDATA OF DMINTERPRETER" 

USING DATA-REQUEST. DATA-BUFFER 

GIVING RESULT. 
IF RESULT =1 

PERFORM EXCEPTION-HANDLER. 

MOVE "PUT REAL EMP EMP-SSN" TO DATA-REQUEST. 
MOVE "573230911" TO DATA-BUFFER. 
CALL "DBDATA OF DMINTERPRETER" 

USING DATA-REQUEST, DATA-BUFFER 

GIVING RESULT. 
IF RESULT = 1 

PERFORM EXCEPTION-HANDLER. 

MOVE "PUT REAL EMP EMP-DATE-HIRED" TO DATA-REQUEST. 
MOVE "811223" TO DATA-BUFFER. 
CALL "DBDATA OF DMINTERPRETER" 

USING DATA-REQUEST. DATA-BUFFER 

GIVING RESULT. 
IF RESULT =1 

PERFORM EXCEPTION-HANDLER. 

MOVE "PUT STRING EMP EMP-LNAME" TO DATA-REQUEST. 
MOVE "STACK" TO DATA-BUFFER. 
CALL "DBDATA OF DMINTERPRETER" 

USING DATA-REQUEST, DATA-BUFFER 

GIVING RESULT. 
IF RESULT =1 

PERFORM EXCEPTION-HANDLER. 

USING DBPUTDISPLAY ENTRY POINT 

MOVE "EMP-FNAME" TO ITEM-NAME. 

MOVE "CATHY" TO VAR-1. 

CALL "DBPUTDISPLAY OF DMINTERPRETER" 

USING DATA-SET-NAME, ITEM-NAME, VAR-1 

GIVING RESULT. 
IF RESULT =1 

PERFORM EXCEPTION-HANDLER. 

USING DBPUTBOOLEAN 

MOVE "EMP-SEC-CLEAR" TO ITEM-NAME. 

MOVE "TRUE" TO VAR-1. 

CALL "DBPUTBOOLEAN OF DMINTERPRETER" 

USING DATA-SET-NAME. ITEM-NAME, VAR-1 

GIVING RESULT. 
IF RESULT = 1 

PERFORM EXCEPTION-HANDLER. 
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* RECORD SETUP IN USER WORK AREA * 
*************************************************** 

* EMP EMP EMP EMP EMP EMP EMP * 

* NO LNAME FNAME SSN DATE-HIRED SEC-CLEAR SALARY * 
*_ * 

* 11 STACK CATHY 573230911 811223 TRUE 9001.90 * 



****************************************************************** 
* STORING A RECORD * 



CALL "DBBEGINTRANSACTION OF DMINTERPRETER" 

USING P-AUDIT 

GIVING RESULT. 
IF RESULT = 1 

PERFORM EXCEPTION-HANDLER. 
CALL "DBSTORE OF DMINTERPRETER" 

USING DATA-SET-NAME 

GIVING RESULT. 
IF RESULT = 1 

PERFORM EXCEPTION-HANDLER. 
CALL "DBENDTRANSACTION OF DMINTERPRETER" 

USING P-AUDIT 

GIVING RESULT. 
IF RESULT = 1 

PERFORM EXCEPTION-HANDLER. 




CALL "DBRECREATE OF DMINTERPRETER" 

USING DATA-SET-NAME, SPACE-1 

GIVING RESULT. 
IF RESULT = 1 

PERFORM EXCEPTION-HANDLER. 

MOVE "PUT REAL EMP EMP-NO" TO DATA-REQUEST. 
MOVE "12" TO DATA-BUFFER. 
CALL "DBDATA OF DMINTERPRETER" 

USING DATA-REQUEST, DATA-BUFFER 

GIVING RESULT. 
IF RESULT = 1 

PERFORM EXCEPTION-HANDLER. 
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MOVE "PUT REAL EMP EMP-SSN" TO DATA-REQUEST. 
MOVE "549927328" TO DATA-BUFFER. 
CALL "DBDATA OF DMINTERPRETER" 

USING DATA-REQUEST, DATA-BUFFER 

GIVING RESULT. 
IF RESULT = 1 

PERFORM EXCEPTION-HANDLER. 

MOVE "PUT REAL EMP EMP-DATE-HIRED" TO DATA-REQUEST. 
MOVE "811228" TO DATA-BUFFER. 
CALL "DBDATA OF DMINTERPRETER" 

USING DATA-REQUEST.DATA-BUFFER 

GIVING RESULT. 
IF RESULT = 1 

PERFORM EXCEPTION-HANDLER. 

MOVE "PUT STRING EMP EMP-LNAME" TO DATA-REQUEST. 
MOVE "WOLVERTON" TO DATA-BUFFER. 
CALL "DBDATA OF DMINTERPRETER" 

USING DATA-REQUEST, DATA-BUFFER 

GIVING RESULT. 
IF RESULT = 1 

PERFORM EXCEPTION-HANDLER. 

MOVE "EMP-FNAME" TO ITEM-NAME. 

MOVE "LAURA" TO VAR-1. 

CALL "DBPUTDISPLAY OF DMINTERPRETER" 

USING DATA-SET-NAME, ITEM-NAME, VAR-1 

GIVING RESULT. 
IF RESULT = 1 

PERFORM EXCEPTION-HANDLER. 
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* SETUP OF RE-CREATED RECORD IN USER WORK AREA * 
************************************************* 

* EMP EMP EMP EMP EMP EMP EMP * 

* NO LNAME FNAME SSN DATE-HIRED SEC-CLEAR SALARY * 
* . * 

* 12 WOLVERTON LAURA 549927328 811228 TRUE 9001.90* 
****************************************************************** 

CALL "DBBEGINTRANSACTION OF DMINTERPRETER" 

USING P-AUDIT 

GIVING RESULT. 
IF RESULT = 1 

PERFORM EXCEPTION-HANDLER. 
CALL "DBSTORE OF DMINTERPRETER" 

USING DATA-.SET-NAME 

GIVING RESULT. 
IF RESULT = 1 

PERFORM EXCEPTION-HANDLER. 
CALL "DBENDTRANSACTION OF DMINTERPRETER" 

USING P-AUDIT 

GIVING RESULT. 
IF RESULT = 1 

PERFORM EXCEPTION-HANDLER. 

****************************************************************** 

* SETTING DATA SET TO THE BEGINNING * 



CALL "DBSET OF DMINTERPRETER" 

USING DATA-SET-NAME, BEGIN-1 

GIVING RESULT. 
IF RESULT = 1 

PERFORM EXCEPTIONrHANDLER. 

****************************************************************** 
* FINDING A RECORD * 



CALL "DBFIND OF DMINTERPRETER" 

USING FIRST-1, DATA-SET-NAME, CONDITION-1 

GIVING RESULT. 
IF RESULT = 1 

PERFORM EXCEPTION-HANDLER. 
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CALL "DBLOCK OF DMINTERPRETER" 

USING FIRST-1, DATA-SET-NAME, CONDITION-1 

GIVING RESULT. 
IF RESULT = 1 

PERFORM EXCEPTION-HANDLER. 



************************************************^ 

* VERIFYING ITEMS IN RECORD * 

* 

* USING DBDATA ENTRY POINT 
* 

MOVE "GET REAL EMP EMP-NO" TO DATA-REQUEST. 
CALL "DBDATA OF DMINTERPRETER" 

USING DATA-REQUEST, DATA-BUFFER 

GIVING RESULT. 
IF RESULT =1 

PERFORM EXCEPTION-HANDLER. 



MOVE "GET REAL EMP EMP-SALARY" TO DATA-REQUEST. 
CALL "DBDATA OF DMINTERPRETER" 

USING DATA-REQUEST, DATA-BUFFER 

GIVING RESULT. 
IF RESULT = 1 

PERFORM EXCEPTION-HANDLER. 

MOVE "GET REAL EMP EMP-SSN" TO DATA-REQUEST. 
CALL "DBDATA OF DMINTERPRETER" 

USING DATA-REQUEST, DATA-BUFFER 

GIVING RESULT. 
IF RESULT = 1 

PERFORM EXCEPTION-HANDLER. 

MOVE "GET REAL EMP EMP-DATE-HIRED" TO DATA-REQUEST. 
CALL "DBDATA OF DMINTERPRETER" 

USING DATA-REQUEST, DATA-BUFFER 

GIVING RESULT. 
IF RESULT =1 

PERFORM EXCEPTION-HANDLER. 

MOVE "GET STRING EMP EMP-LNAME" TO DATA-REQUEST. 
CALL "DBDATA OF DMINTERPRETER" 

USING DATA-REQUEST,DATA-BUFFER 

GIVING RESULT. 
IF RESULT = 1 

PERFORM EXCEPTION-HANDLER. 
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USING DBGETDISPLAY ENTRY POINT 

MOVE "EMP-FNAME" TO ITEM-NAME. 

CALL "DBGETDISPLAY OF DMINTERPRETER" 

USING DAT A-S ET-NAME , I TEM-NAME , VAR- 1 

GIVING RESULT. 
IF RESULT ^ 1 

PERFORM EXCEPTION-HANDLER. 

USING DBGETBOOLEAN 

MOVE "EMP-SEC-CLEAR" TO ITEM-NAME. 
CALL "DBGETBOOLEAN OF DMINTERPRETER" 

USING DATA-SET-NAME, ITEM-NAME, VAR-1 

GIVING RESULT. 
IF RESULT =1 

PERFORM EXCEPTION-HANDLER. 




CALL "DBFREE OF DMINTERPRETER" 
USING DATA-SET-NAME 
GIVING RESULT. 

IF RESULT = 1 

PERFORM EXCEPTION-HANDLER. 




CALL "DBFIND OF DMINTERPRETER" 

USING FIRST-1, DATA-SET-NAME, SPACE-1 

GIVING RESULT. 
IF RESULT = 1 

PERFORM EXCEPTION-HANDLER. 
CALL "DBFIND OF DMINTERPRETER" 

USING PRIOR-1, DATA-SET-NAME, SPACE-1 

GIVING RESULT. 
IF RESULT = 1 

PERFORM EXCEPTION-HANDLER. 
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****************************************************^ 

* USING DBVERB * 
*************************************************** 

* 

* USING DBVERB ON A SET STATEMENT 
* 

MOVE "SET EMP TO BEGINNING" TO DATA-REQUEST. 
CALL "DBVERB OF DMINTERPRETER" 

USING DATA-REQUEST 

GIVING RESULT. 
IF RESULT =1 

PERFORM EXCEPTION-HANDLER. 

* 

* USING DBVERB ON A SEARCH STATEMENT 
* 

MOVE "FIND FIRST EMP AT EMP-N0=11" TO DATA-REQUEST. 
CALL "DBVERB OF DMINTERPRETER" 

USING DATA-REQUEST 

GIVING RESULT. 
IF RESULT = 1 

PERFORM EXCEPTION-HANDLER. 

****************************************************************** 

* CLOSING THE DATABASE 

****************************************************************** 

CALL "DBCLOSE OF DMINTERPRETER" 

GIVING RESULT. 
IF RESULT = 1 

PERFORM EXCEPTION-HANDLER. 

CLOSE REMOTEFILE. 
STOP RUN. 

EXCEPTION-HANDLER. 

CALL "DBSTATUS OF DMINTERPRETER" 

USING EXCEPTION-WORD. 
CALL "DBEXCEPTIONNAME OF DMINTERPRETER" 

USING EXCEPTION-WORD, EXCEPTION-NAME. 
MOVE EXCEPTION-NAME TO REMOTE-REC. 
WRITE REMOTE-REC. 

CALL "DBEXCEPTIONTEXT OF DMINTERPRETER" 
USING EXCEPTION-WORD, EXCEPTION-MSG. 
MOVE EXCEPTION-MSG TO REMOTE-REC. 
WRITE REMOTE-REC. 

END-OF-PROGRAM. 
EXIT PROGRAM. 
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FORTRAN?? Application Program Using the 
Interpretive Interface 

************************************************** 

* This program uses the FORTRAN?? declaration of library entry points * 

* from the DATABASE/DMINTERPRETER symbolic file rather than * 

* explicitly declaring each entry point. * 

* 

$ RESET FREE 

* 

*********************************************************************** 

* FORTRAN?? LIBRARY AND ENTRY POINT DECLARATIONS * 
*********************************************************************** 

BLOCK GLOBALS 

LIBRARY DMI (TITLE="DMINTERPRETER/EMPJOB. ") 

END 



$ INCLUDE "DATABASE/DMINTERPRETER" 20200000-20249999 




SUBROUTINE EXCEPT 

$ INCLUDE "DATABASE/DMINTERPRETER" 20290000-20299999 

CHARACTER MSG *?0 
LOGICAL RESULT 

RESULT = DBSTAT( ) 

CALL DBEXCN (RESULT. MSG) 
WRITE (6, 200) MSG 

CALL DBEXCT (RESULT, MSG) 
WRITE (6, 200) MSG 
200 FORMAT (1X,A) 
RETURN 
END 



$ INCLUDE "DATABASE/DMINTERPRETER" 20290000-20299999 
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* START OF MAIN PROGRAM * 



CHARACTER DSNAMP 


*4 
*t 


/"FMP" / 


* FTD^T 
r 1 Ko 1 




/••FTDCT" / 
/ r i KO 1 / } 


* PRIOR 


*10 


/"PRIOR"/, 


* NEXT 


*10 


/"NEXT"/. 


* BEGIN 


*9 


/"BEGINNING"/, 


* AUDIT 


*10 


/"AUDIT"/, 


* UPDATE 


*6 


/"UPDATE"/, 


* SPACE 


*1 


/" 7. 


* COND 


*9 


/"EMP-N0=11"/, 


* DATREQ 


*40 




* DATBUF 


*22 


» 


* ITMNAM 


*13 




* MSG 


*70 


9 


* EXPR3 


*22 





LOGICAL RSLT, 
EXPR4 



DOUBLE PRECISION EXPR2 
REAL EXPRl 



* OPENING THE DATABASE * 



RSLT = DBOPEN (UPDATE) 
IF (RSLT) CALL EXCEPT 



* DELETING A RECORD * 



RSLT = DBBTR(AUDIT) 
IF (RSLT) CALL EXCEPT 

RSLT = DBDEL(FIRST,DSNAME,COND) 
IF (RSLT) CALL EXCEPT 

RSLT = DBETR(AUDIT) 
IF (RSLT) CALL EXCEPT 
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************************************************** 

* CREATING A RECORD * 

*********************************************************************** 



RSLT = DBCR(DSNAME.SPACE) 

IF (RSLT) CALL EXCEPT 
*********************************************************************** 

* FILLING IN A RECORD * 



USING DBPUTREAL ENTRY POINT 

ITMNAM = "EMP-NO" 
EXPRl = 11 

RSLT = DBPUTR(DSNAME, ITMNAM, EXPRl) 
IF (RSLT) CALL EXCEPT 



ITMNAM = "EMP-SALARY" 
EXPRl = 4500.95 

RSLT = DBPUTR(DSNAME, ITMNAM, 2 * EXPRl) 
IF (RSLT) CALL EXCEPT 



USING DBPUTDOUBLE ENTRY POINT 

ITMNAM = "EMP-SSN" 
EXPR2 = 573230911 

RSLT = DBPUTD(DSNAME, ITMNAM, EXPR2 - 11) 
IF (RSLT) CALL EXCEPT 



USING DBDATA ENTRY POINT 

DATREQ = "PUT REAL EMP EMP-DATE-HIRED" 

DATBUF = "811223" 

RSLT = DBDATA(DATREQ, DATBUF) 

IF (RSLT) CALL EXCEPT 

DATREQ = "PUT CHARACTER EMP EMP-LNAME" 

DATBUF = "STACK" 

RSLT = DBDATA(DATREQ, DATBUF) 

IF (RSLT) CALL EXCEPT 



USING DBPUTCHARACTER ENTRY POINT 

ITMNAM = "EMP-FNAME" 
EXPR3 = "CATHY" 

RSLT = DBPUTC(DSNAME, ITMNAM, EXPR3 (1:5) // "LINA") 
IF (RSLT) CALL EXCEPT 
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USING DBPUTLOGICAL ENTRY POINT 

ITMNAM = "EMP-SEC-CLEAR" 
EXPR4 = .TRUE. 

RSLT = DBPUTL(DSNAME, ITMNAM,. NOT. EXPR4) 
IF (RSLT) CALL EXCEPT 



* RECORD SETUP IN USER WORK AREA * 

* * 

* EMP EMP EMP EMP EMP EMP EMP * 

* NO LNAME FNAME SSN DATE-HIRED SEC-CLEAR SALARY * 
* ^ . * 

* 22 STACIC CATHY 573230900 811223 FALSE 9001.9 * 



* STORING A RECORD * 



RSLT = DBBTR(AUDIT) 
IF (RSLT) CALL EXCEPT 

RSLT = DBSTORE(DSNAME) 
IF (RSLT) CALL EXCEPT 

RSLT = DBETR(AUDIT) 
IF (RSLT) CALL EXCEPT 




RSLT = DBRECR(DSNAME, SPACE) 
IF (RSLT) CALL EXCEPT 

ITMNAM = "EMP-NO" 
EXPRl =12 

RSLT = DBPUTR(DSNAME,ITMNAM,EXPR1) 
IF (RSLT) CALL EXCEPT 



ITMNAM = "EMP-SSN" 
EXPR2 = 549273281 

RSLT = DBPUTD(DSNAME, ITMNAM, EXPR2 - 12) 
IF (RSLT) CALL EXCEPT 



DATREQ = "PUT STRING EMP EMP-LNAME" 

DATBUF = "BLACK" 

RSLT = DBDATA (DATREQ, DATBUF) 

IF (RSLT) CALL EXCEPT 
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ITMNAM = "EMP-FNAME" 
EXPR3 = "SARAH" 

RSLT = DBPUTC(DSNAME, ITMNAM, EXPR3 (1:5) // "LEE") 
IF (RSLT) CALL EXCEPT 



RSLT = DBBTR(AUDIT) 
IF (RSLT) CALL EXCEPT 

RSLT = DBSTORE(DSNAME) 
IF (RSLT) CALL EXCEPT 

RSLT = DBETR (AUDIT) 
IF (RSLT) CALL EXCEPT 

* SETTING DATA SET TO THE BEGINNING * 

***************************************************** 



RSLT = DBSET(DSNAME, BEGIN) 
IF (RSLT) CALL EXCEPT 



*********************************************************************** 

* FINDING A RECORD * 

*********************************************************************** 



RSLT = DBFIND(FIRST,DSNAME,COND) 
IF (RSLT) CALL EXCEPT 




RSLT = DBLOCK(FIRST,DSNAME.COND) 
IF (RSLT) CALL EXCEPT 



* VERIFYING ITEMS IN A RECORD 

* 
* 

* USING DBGETREAL ENTRY POINT 
* 

ITMNAM = "EMP-NO" 

RSLT = DB6ETR(DSNAME,ITMNAM.EXPR1) 
IF (RSLT) CALL EXCEPT 

ITMNAM = "EMP-SALARY" 

RSLT = DBGETR(DSNAME,ITMNAM,EXPR1) 

IF (RSLT) CALL EXCEPT 
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* 
* 

* USING DBGETDOUBLE ENTRY POINT 

* 

ITMNAM = "EMP-SSN" 

RSLT = DBGETD(DSNAME. ITMNAM, EXPR2) 

IF (RSLT) CALL EXCEPT 

* 
* 

* USING DBDATA ENTRY POINT 
* 

DATREQ = "GET REAL EMP EMP-DATE-HIRED" 
RSLT = DBDATA(DATREQ,DATBUF) 
r IF (RSLT) CALL EXCEPT 



DATREQ = "GET CHARACTER EMP EMP-LNAME" 
RSLT = DBDATA (DATREQ, DATBUF) 
IF (RSLT) CALL EXCEPT 



USING DBGETCHARACTER ENTRY POINT 

ITMNAM = "EMP-FNAME" 

RSLT = DBGETC(DSNAME, ITMNAM, EXPR3) 

IF (RSLT) CALL EXCEPT 



* USING DBGETLOGICAL ENTRY POINT 

ITMNAM = "EMP-SEC-CLEAR" 

RSLT = DBGETL(DSNAME, ITMNAM, EXPR4) 

IF (RSLT) CALL EXCEPT 

* FREEING A RECORD * 



RSLT = DBFREE(DSNAME) 
IF (RSLT) CALL EXCEPT 



CAUSING AN EXCEPTION 



RSLT = DBSET(DSNAME, BEGIN) 
IF (RSLT) CALL EXCEPT 



RSLT = DBFIND(PRIpR,DSNAME,SPACE) 
IF (RSLT) CALL EXCEPT 
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************************************************** 

* USING DBVERB * 
*********************************************************************** 

* 

* USING DBVERB ON A SET STATEMENT 
* 

RSLT = DBVERB ("SET EMP TO BEGINNING") 
IF (RSLT) CALL EXCEPT 

* 

* USING DBVERB ON A SEARCH STATEMENT 
* 

RSLT = DBVERB("FIND FIRST EMP AT EMP-N0=11") 
IF (RSLT) CALL EXCEPT 

* 

* USING DBVERB ON A STATUS STATEMENT 
* 

RSLT = DBVERB("SET EMP TO BEGINNING") 

IF (RSLT) CALL EXCEPT 

RSLT = DBVERB("FIND PRIOR EMP") 

RSLT = DBVERB("DMSTATUS") 

CALL DBEXCN (RSLT, MSG) 

CALL DBEXCT( RSLT, MSG) 

*********************************************************************** 

* CLOSING THE DATABASE * 
*********************************************************************** 



RSLT = DBCLOSE( ) 

IF (RSLT) CALL EXCEPT 

END 
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Appendix D 

Understanding Railroad Diagrams 



What Are Railroad Diagrams? 



Railroad diagrams are diagrams that show you the rules for putting words and S5rtnbols 
together into commands and statements that the computer can understand. These 
diagrams consist of a series of paths that show the allowable structure, constants, and 
variables for a command or a statement. Paths show the order in which the command or 
statement is constructed. Paths are represented by horizontal and vertical lines. Many 
railroad diagrams have a number of different paths you can take to get to the end of the 
diagranL For example: 



— REMOVE 



\- SOURCE -I 
L- OBJECT -J 



If you follow this railroad diagram from left to ri^t, you will discover three acceptable 
commands. These commands are 



• REMOVE 

• REMOVE SOURCE 

• REMOVE OBJECT 

If all railroad diagrams were this simple, this explanation could end here. However, 
because the allowed ways of commtmicating with the computer can be comply railroad 
diagrams sometimes must also be complex. 

Regardless of the level of complexity, all railroad diagrams are visual representations of 
commands and stat^ents. Railrosd diagrams are intended to 

• Show the mandatoiy items. 

• Show the user-sdected items. 

• Present the order in which tiie items must appear. 

• Show the number of times an item can be repeated. 

• Show the necessary punctuation. 



To familiarize you with railroad diagrams, this e^lanation describes the elem^ts of the 
diagrams and provides examples. 

Some of the actual railroad diagrams you will encounter mig^t be more complex. 
However, all railroad diagrams, simple or complex, follow the same basic rules. They 
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all consist of paths that represent the allowable structure, constants, and variables for 
commands and statements. 

By following railroad diagrams, you can easify understand the correct syntax for 
commands and statements. Once you become proficient in the use of railroad notation, 
the diagrams serve as quick references to the commands and statements. 

Constants and Variables 

A constant is an item that capnot be altered. You must enter the constant as it appears 
in the diagram, either in full or as an allowable abbreviation. If a constant is partially 
imderlined, you can abbreviate the constant by entering only the underlined letters. In 
addition to the imderlined letters, any of the remaining letters can be entered. If no part 
of the constant is imderlined, the constant cannot be abbreviated. Constants can be 
recognized by the fact that they are never enclosed in angle brackets ( < > ) and are in 
uppercase letters. 

A variable is an item that represents data. You can replace the variable with data that 
meets the requirements of the particular command or statement. When replacing a 
variable with data, you must follow the rules defined for the particular conmiand or 
statement. Variables appear in railroad diagrams enclosed in angle brackets. 

In the following example, BEGIN and END are constants while < statement list> is a 
variable. The constant BEGIN can be abbreviated since it is partia% imderlined. Valid 
abbreviations for BEGIN are BE, BEG, and BEGI. 

— B£GIN — <statement list>— END 1 

Constraints 

Constraints are used in a railroad diagram to control progression through the diagram. 
Constraints consist of symbols and unique railroad diagram line paths. They include 

• Vertical bars 

• Percent signs 

• Eight arrows 

• Required items 

• User-selected items 

• Loops 

• Bridges 

A description of each item follows. 
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Vertical Bar 

The vertical bar symbol ( | ) represents the end of a raiboad diagram and indicates the 
command or statement can be followed by another command or statement. 

— SECONDWORD — ( — arithmetic expression? — ) 1 

Percent Sign 

The percent sign (%) represents the end of a railroad diagram and indicates the 
command or statement must be on a line by itself. 

_ STOP % 

Right Arrow 

The right arrow symbol ( > ) is used when the railroad dis^am is too long to fit on one 
line and must continue on the next. A right arrow appears at the end of the first line and 
another right arrow appears at the beginning of the next line. 

— SCALERIGHT — ( — <arithmetic expression? — , > 

->-<arithmetic expression? — ) 1 

Required Items 

A required item can be either a constant, a variable, or punctuation. A required item 
appears as a single entry, by itself or with other items, on a horizontal line. Required 
items can also exist on horizontal lines within alternate paths or nested (lower-level) 
diagrams. If the path you are following contains a required item, you must enter the 
item in the command or statement; the required item cannot be omitted. 

In the following example, the word EVENT is a required constant and < identifier > is a 
required variable: 

— EVENT — <ielentifier> 1 

User-Selected Items 

User-selected items appear one below the other in a vertical list. You can choose any one 
of the items from the list. If the list also contains an empty path (solid line), none of 
the choices are required. A user-selected item can be either a constant, a variable, or 
punctuation. In the following railroad diagram, either the plus sign ( -f ) or minus sign (-) 
can be entered before the required variable < arithmetic e:q)ression > , or the symbols 
can be disregarded because the diagram also contains an empty path. 

— I 1— <ari thmet i c expressi on> 1 
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Loop 

A loop represents an item or group of items that you can repeat. A loop can span all or 
part of a railroad diagram. It alvrays consists of at least two horizontal lines, one below 
the other, connected on both sides vertical liaes. The top line is a ri^t-to-left path 
that contains information about repeating the loop. 

Some loops include a return character. A return character is a character — often a 
comma (,) or semicolon (;) — required before each repetition of a loop. If there is no 
return character, the items must be separated by one or more blank spaces. 

r* '» 1 

— '—cfield valuo-J : — : 



Bridge 

Sometimes a loop also includes a bridge, which is used to show the maximum mmiber of 
times the loop can be repeated. The bridge can precede the contents of the loop, or it 
can precede the return character (if any) on the upper line of the loop. 

The bridge determines the number of times you can cross that point in the diagram. The 
bridge is an integer enclosed in sloping lines (/ \). Not all loops have bridges. Those that 
do not can be repeated any number of times imtil all valid entries have been used. 

In the first bridge example, you can enter LINKAGE or RUNTIME no more than two 
times. In the second bridge example, you can enter LINKAGE or RUNTIME no more 
than three times. 

— •^/2\-T- LINKAGE -r-^ 1 

«- RUNTIME -1 



I^^ ^LINKAGE -|— * 1 

I- RUNTIME -J 

In some bridges an asterisk (*) follows the number. The asterisk means that you must 
select one item from the group. 



•/l*\-r- LINKAGE -T-i : 1 

L. RUNTIME -J 

The following figure shows the types of ccmstraints used in railroad diagrams. 
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SYMBOL/ PATH 


EXPLANATION 


1 


Vertical bar. Indicates that the 
commaTid or statement can be followed 
by another coimnaTid or statement. 




Percent sign. Indicates that the 
command or statement must be on a 
line by itself. 


> 

> 


Right arrow. Indicates that the 
diagram occupies more than one 
line. 


required >_> 


Required items. Indicates the 
constants, variables, and 
punctuation that must be entered 
in a command or statement. 




- YES — 

- NO — 




User-selected items. Indicates the 
items that appear one below the 
other in a vertical list. You 

select which item or items to include. 








A loop. Indicates an item or group 
of items that can be repeated. 


— J_/2\_J— 


A bridge. Indicates the maximum • 
number of times a loop can be 
repeated. 



Figure D-1. Railroad Constraints 



Following the Paths of a Railroad Diagram 

The paths of a railroad diagram lead you throt^ the command or statement from 
beginning to end. Some railroad diagrams have only one path, while others have several 
alternate paths. The following railroad diagram indicates there is only one path that 
requires the constant LINKAGE and the variable < linkage mnemonic > : 

— LINKAGE — <1inkage mnemonic> 1 

Alternate paths provide choices in the construction of commands and statements. 
Alternate paths are provided by loops, user-selected items, or a combination of both. 
More complex railroad diagrams can consist of many alternate paths, or nested 
Gower-level) diagrams, that show a further level of detail. 

For example, the foUowii^ railroad diagram consists of a top path and two alternate 
paths. The top path includes an ampersand (&) and the constants (that are 
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user-selected items) in tiie vertical Ust. These constants are within a loop that can be 
repeated any number of times until all options have been selected. The first alternate 
path requires the ampersand and the required constant ADDRESS. The second 
alternate path requires the ampersand followed by the required constant ALTER and 
the required variable < new value > . 



— & 



lYPE - 
h ASCII 
fiCL 



DECIMAL - 

- £BCDIC — 

- EEX 



I- OCTAL - 

- MDRESS 

ALTER — <new values 



Railroad Diagram Examples with Sample Input 

The following examples show five railroad diagrams and possible command and 
statement constructions based on the paths of these diagrams. 

Example 1 

<1ock stateinent> 

— LOCK — ( — <file identifier> — ) 1 



Sample input 

LOCK (FILE4) 



Explanation 

LOCK is a constant and cannot be altered. Because no part 
of the word is underlined, the entire word must be entered. 

The parentheses are required punctuation and FILE4 is a 
sample file identifier. 



Example 2 

<open statement> 
— OPEN 



I- INQUIRY - 
L- UPDATE — I 



-<database name>- 



Sample Input 

OPEN DATABASEl 



OPEN INQUIRY DATABASEl 



Explanation 

The constant OPEN is followed tjy the variable DATABASEl, 
which Is a database name. 

The railroad diagram shows two user-selected items, 
INQUIRY and UPDATE. However, t)ecause there Is an empty 
path (solid line), these entries are not required. 

The constant OPEN is followed t)y the user-seiected constant 
INQUIRY and the variable DATABASEl. 

continued 
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continued 
Sample Input 

OPEN UPDATE DATABASEl 



Explanation 

The constant OPEN is followed by the user-selected constant 
UPDATE and the variable DATABASEl. 



Example 3 

<generate statement> 
— GENERATE — <subset5 



-r- NULL — 
L-<subset>- 



- AND 

- OR - 
+ — 



-<subset5 



Sample Input 
GENERATE Z = NULL 

GENERATE Z = X 

GENERATEZ = XANDB 



GENERATE Z = X + B 



Explanation 

The GENERATE constant is followed by the variable Z, an 
equal sign (=}, and the user-selected constant NULL. 

The GENERATE constant is followed by the variable Z, an 
equal sign, and the user-selected variable X. 

The GENERATE constant Is followed by the variable Z, an 
equal sign, the user-selected variable X, the AND command 
(from the list of user-selected items in the nested path), and 
a third variable, B. 

The GENERATE constant is followed by the variable Z, an 
equal sign, the user-selected variable X, the plus sign (from 
the list of user-selected items in the nested path), and a third 
variable, B. 



Example 4 

<entity reference declaration> 

— ENTITY REFERENCE -LUentity ref IDs 



( — <class ID> — ) 



Sample Input 

ENTITY REFERENCE ADVISORl (INSTRUCTOR) 



ENTITY REFERENCE ADVISORl (INSTRUCTOR), 
ADVIS0R2 (ASST INSTRUCTOR) 



Explanation 

The required item ENTITY 
REFERENCE is followed by the 
variable ADVISORl and the variable 
INSTRUCTOR. The parentheses are 
required. 

Because the diagram contains a 
loop, thie pair of variables can be 
repeated any number of times. 
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Example 5 

— PS — MODIFY 



»- ALL 



■I— <request nuniber> r 

>— <request number? <request numbers—' 



£XCEPTIONS 



-j-<file attribute phrase>- 

— j--<pnnt modifier phrase>- 



Sample Input 

PS MODIFY 11159 

PS MODIFY 11159,11160,11163 



PS MOD 11159-11161 DESTINATION 
"LP7" 



PS MOD ALL EXCEPTIONS 



Explanation 

The constants PS and MODIFY are followed 
by the variable 11159, which is a request 
number. 

Because the diagram contains a loop, the 
variable 11159 can be followed by a comma, 
the variable 11160, another comma, and the 
final variable 11163. 

The constants PS and MODIFY are followed 
by the user-selected variables 
11159-11161, which are request numbers, 
and the user-selected variable DESTINATION 
= "LP?", which is a file attribute phrase. 
Note that the constant MODIFY has been 
abbreviated to its minimum allowable form. 

The constants PS and MODIFY are followed 
by the user-selected constants ALL and 
EXCEPTIONS. 
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In this glossary, definitions taken from outside sources are preceded by an abbreviation enclosed 
in parentheses. Unless otherwise noted, all definitions that pertain to COBOL also pertain to 
COBOL74 and COBOL85. 



abort 



ABSN 



access 



To terminate an active program or session abnormally and, sometimes, to attempt to 
restart it. 



See audit block serial number. 



(1) To perform an action on an object. Possible actions depend on the type of object; for 
example, interrogating or assigning a value to a variable, reading from or writing to a file, 
or invoking a procedure. (2) A logical index structure that defines the physical ordering 
of records in direct, ordered, and random data sets. An access functions like a set, but no 
physical file is associated with an access. 

access mode 

The manner in which records are to be operated on within a file. The two possible access 
modes are random and sequential. 

Accessroutines 

Routines that perform all physical and logical management of a database and allow many 
users to access the database concurrently. Each data management statement that a user 
language program executes invokes a portion of the Accessroutines to perform all file 
management ftmctions that the statement requires. 

active query 

In database management, a query that tiie system can process. All queries activated 
within transaction state are deactivated at the end of transaction state. 

ACTUALNAME clause 

A dause that permits tiiie renaning of a library entry point within a user prc^ram by 
using a different procedure identifier to link to the original library entry point name. 
This clause is used in ALGOL, FORTRAN??, and PL/1 application programs when a 
procedure is declared to be an entiy point a particular library. 



ADDS 



See Advanced Data Dictionary 33rstem. 



Advanced Data Dictionary System (ADDS) " 

A software product tiiat allows for the centralized definition, storage, and retrieval of 
data descriptions. 
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afterimage 

The image of a database record in the audit trail after an update operation is performed. 

ALGOL 

Algorithmic language. A structured, high-level pr<^amming language that provides 
the basis for the stack architecture of the Unisys A Series systems. ALGOL was the 
first block-structured language developed in the 1960s and served as a basis for such 
languages as Pascal and Ada. It is still used extensively on A Series systems, primarily 
for systems programming. 

alpha data item of usage Eanji 

A database or file item that is declared in either the Data and Structure Definition 
Language (DASDL) or a file description as being ALPHA USAGE IS KANJI. 

alpha item 

A data item that stores alphanumeric information (letters, numbers, special characters, 
and blanks) as EBCDIC characters. An alpha item cannot be used in calculations. 

alphabetic character 

A character that belongs to the following set of letters in either uppercase or lowercase: 
A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, y W, X, Y, Z, and the space 
(blank). 

alphanumeric character 

Any character in the computer's character set. 

ANSI 

American National Standards Institute. A nongovernmental, nonprofit organization that 
is the central body for coordinating voluntary standards in the United States. ANSI also 
serves as the United States member of the International Standards Organization (ISO). 

arithmetic expression 

An expression containing any of the foDowing: a nimieric variable, a nimieric elementary 
item, a numeric literal, identifiers and literals separated by arithmetic operators, two 
arithmetic expressions separated by an arithmetic operator, or an arithmetic expression 
enclosed in parentheses. 

arithmetic function 

A function containing calculations that produce a numeric result based on one or more 
records. 

attribute setting entry point 

In the DMINTEBPBETER libraiy, an entry point that restricts the number of times 
the DMINTEBPBETER libraiy can call the Accessroutines to complete a find or lock 
operation. 

audit block serial number (ABSN) 

A number associated with a block in the audit file. The first block in the fii^t audit file is 
noted as ABSN 0. The ABSN is incremented by one through the last audit file. 
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audit trail 

A file produced by the Accessroutines that contains various control records and a 
sequence of before-update and after-update record images resulting from changes to the 
database. The audit trail is used to recover the database and supply restart information 
to programs after a hardware or software failure has occurred. 

audited database 

A database that stores a record of changes (called the audit trail), which can be used for 
database recovery if a hardware or software failure occurs. 

automatic subset 

A subset declared with a condition that specifies which members of the data set are to 
be included in the subset. Entries are automatically inserted into or removed from the 
subset when records are added to or deleted from the data set. 



B 

back out 

To undo changes made against a database and to roll back the progress of one or more 
transactions to a previously consistent state. 

beforeimage 

The image of a database record in the audit trail before an update operation is 
performed. 

binary search 

A quick method of searching for records that are in a known sequence by successively 
halving the area to be searched. 

block 

(1) A group of physically adjacent records that can be transferred to or from a physical 
device as a group. (2) A program, or a part of a program, that is treated by the processor 
as a discrete vmt. Examples are a procedure in ALGK3L, a procedure or function in 
Pascal, a subroutine or function in FORTRAN, or a complete COBOL programs 

Boolean 

Pertaining to variables, data items, and attributes having a value of TRUE or FALSE. 
Boolean item 

A data item that stores information having a logical value of TRUE or FALSE. 



caU 

A programmatic request for another procedure or program to execute. 
CALL statement 

In COBOL, the CALL nonnumeric literal statement is the onfy construct tibat enables 
a pr(^ram to call a library antry point. The CALL statement can pass required 
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parameters in an optional USING clause and receive a result in an optional GIVING 
clause. 

CANDE 

See Command and Edit. 

CHANGE ATTRIBUTE statement 

In COBOL, the statement that is the only construct that can be used to change library 
attributes. When programming for the interpretive interface, this statement is used to 
change the TITLE attribute of the library to the actual name of the library object code 
ffle. 

character 

The actual or coded representation of a digit, letter, or special symbol in display form. 

COBOL 

Common Business-Oriented Language. A widely used, procedure-oriented language 
intended for use in solving problems in business data processing. The main 
characteristics of COBOL are the easy readability of programs and a considerable degree 
of machine independence. COBOL is the most widely used procedure-oriented language. 

COBOL74 

A version of the COBOL language that is compatible with the American National 
Standard X3.23-1974. 

COBOL85 

The latest version of the COBOL language. This version is compatible with the 
American National Standard X3.23-1985. 

code file 

See object code file, source file. 

Command and Edit (CANDE) 

A time-sharing message control system (MCS) that enables a user to create and edit 
files, and to develop, test, and execute programs, interactive^. 

Communications Management System (COMS) 

A general message control siystem (MCS) that controls online environments on A Series 
systems. COMS can support the processing of multiprogram transactions, sin^e-station 
remote files, and multistation remote files. 

compile time 

The time during which a compiler analyzes pr(^ram text and generates an object code 
file. 

complex key 

A composed of multiple items. 

COMS 

See C!ommunications Management System. 
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condition 

In COBOL, a status for which a truth value can be determined at execution time. The 
term condition (condition- 1, condition-2, and so forth) implies a conditional expression 
consisting of either a simple condition optionally enclosed in parentheses or a combined 
condition consisting of a combination of simple conditions, logical operators, and 
parentheses, for which a truth value can be determined. See also selection expression. 

control file 

A file containing data file coordination information, audit control information, and 
dynamic database parameter values. 

control item 

A coimt item, population item, or record-type item. 

controlpoint 

A feature that limits the amoimt of audit information scanned by halt/load and Abort 
recovery. The controlpoint is performed when the last process leaves transaction state. 
Halt/load and Abort recovery do not process any audit images prior to the next to last 
controlpoint in the audit. 

count item 

A control item that contains a system-maintained count of the number of counted links 
that refer to a record. 

current path 

A logical reference into a data set or set from which the current record was retrieved, 
current record 

The actual data set record that a program is currently referencing. Each data set has a 
current record, which is contained in the user work area. 

current record area 

See user work area. 

D 

DASDL 

See Data and Structure Definition Language. 

Data and Structure Definition Language (DASDL) 

The language used to describe a database logically and pfaysicalfy, and to specify criteria 
to ensure the integrity of data stored in the database. DASDL is the source language 
tiiat is input to the DASDL compiler, which creates or updates the database description 
file from tiie input. 

data independence 

In data management, the property that establishes the ability to change the structural 
format of a database without requiring changes to or recompilation of unaffected 
application programs that use tiie database. 
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data item 

A field in a database record or transaction format that contains a particular type of 
information. 

data management 

(1) The operating system function of placing and retrieving data in storage and 
protecting its security and integrity. (2) Data administration. 

Data Management System (DMS) 

The system responsible for storing and retrieving data while protecting data security and 
integrity. 

Data Management System n (DMSII) 

A specialized system software package used to describe a database and maintain the 
relationships among the data dements in the database. 

data set 

A collection of related data records stored in a file on a random-access storage device. 
A data set is similar to a conventional file. It contains data items and has logical and 
physical properties similar to files. However, imlike conventional files, data sets can 
contain other data sets, sets, and subsets. 

data set record 

A record contained in a data set, which can be accessed throu^ a DMSII statement. 

data transfer entry point 

A type of entry point peculiar to the DMINTERPitETBR library whereby an item 
needed from a data set record is moved individually to or from a variable or expression 
that has been declared in the application program. 

datatype 

An interpretation applied to a string of bits. Data types can be classified as structured 
or scalar. Structured data types are collections of individual data items of the same or 
different data types, such as arrays and records. Scalar data types include real, integer, 
double precision, complex, logical (also called Boolean), character, pointer, and label. 
Most programming lai^uages provide a declaration statement or a standard convention 
to indicate the data type of a variable. 

database (DB) 

An integrated, centralized system of data files and program utilities desired to support 
an application. The data sets and associated index structures are defined by a sin^e 
description. Ideally, all the permanent data pertinent to a particular application resides 
in a single database. The database is considered a ^obal entity that several applications 
can access and update concurrentliy. 

database administrator (DBA) 

The person or group of people responsible for planning, designing, implementing, and 
maintaining a database. 

database definition 

A description of the logical and physical structures of a database. 
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database equation 

The equation that refers to three operations: the specification of database titles during 
compilation, the run-time manipulation of database titles, and the creation of a Work 
Flow Language (WFL) task equation that overrides compiled-in titles by implicitly 
assigning a value to the DATABASE task attribute. 

database management i^stem (DBMS) 

The software used to store, retrieve, update, report on, and protect data in a database. 

database name 

The unique identifier of a particular database. The rules for constructing a database 
name are the same as those for constructing a file name. 

database stack (DBS) 

A stack that contains all the information necessary for the Accessroutines to manage a 
database. 



DB 



DBA 



DBMS 



DBS 



See database. 

See database administrator. 

See databsise management system. 

See database stack. 



deadlock 

In data management, a situation in which two or more programs have locked records and 
are also attempting to lock records held by each other. 

declaration 

A programming language construct used to identify an object, such as a type or variable, 
to tiie compiler. A dedaration can be used to associate a data lype with the object so that 
the otgect can be used in a program. 

description file 

The file produced by the Data and Structure Definition Language (DASDL) or 
Transaction Formatting Language (TFL) compiler that contains information used when 
compiling all tailored software and all DMSn user-language programs for a particular 
database or transaction base. 

direct data set 

A collection of related data records stored in a file. These records are maintained in key 
value order. One unsigned numeric data item in the record is designated as the key item. 

directory 

(1) In Data Management System n (DMSID, a file with the layout for each field of the 
record that it describes. A directory describes the layout of records within a file. (2) In 
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the Advanced Data Dictionary System (ADDS), a tinique identifier by which one or more 
entities can be grouped. 

directory name 

A name used to refer to a group of files whose file names are identical to the directory 
name, except that the file names have at least one additional node following the directoiy 
name. 

disjoint 

Pertaining to a data set, set, or subset when it is not contained in another data set. 
Contrast with embedded. 



DMINTERPRETER Ubrary 

The object code file within the iaterpretive interface that enables an application program 
to access a DMSII database. 



DMS 
DMSn 



See Data Management System. 



See Data Management System n. 



DMSn recovery 

A database routine that is initiated after a hardware, software, or operations failure 
while a datab£ise is in the update mode. DMSII recovery backs out any partially 
completed transactions by applying audit-trail images to the database to restore it to its 
proper state. It also passes restart information to the programs accessing the database. 

DMSUPPORT Ubrary 

An object code file containing the procedures that are tailored for a particular database. 

doable precision 

Pertaining to an arithmetic value that is represented iatemalty as a signed-magnitude 
mantissa and e:sponent and is contained in two words. 



EBCDIC 



Extended Binary Coded Decimal Int»:dbange Code. An 8-bit code representing 256 
graphic and control characters that are the native character set of most mainframe 



embedded 

Pertaining to a data set, set, or subset contained within another data set. A record of 
an embedded structure must be accessed throu^ the master data, set in which it is 
^bedded. Contrast wi^ das^cmt. 

end of Eanji (EOK) character 

A diaract^ that agnals the end of a Kai^i diaracter string. 
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entry point 

A procedure or function that is a library object. 

EOE 

See end of Kanji character. 

ERGO 

See Extended Retrieval with Graphic Output, 
exception 

In data management, an error result returned to an application program by the data 
management software, explaining the reason a requested database operation was not 
performed. 

exception handling entry point 

In the DMINTERPRETER library, an entry point that aids the programmer in handling 
and interpreting exceptions and errors. 

exception result 

Synonym for result descriptor and exception word. 

exception word 

Synonym for result descriptor and exception result. 

execution time 

The time during which an object code file is executed. Synonym for run time and, in 
COBOL, object tune. 

export 

To send or cany to an outside entity the original significance or function, 
expression 

A combination of operands and operators that results in the generation of a sin^e value. 

Extended Retrieval with Graphic Output (ERGO) 

A program for Data Management System n (DMSII) database and file access, and for 
report generation. 

F 

field item 

A data item that can contain an unsigned integer or Boolean values. 

Field Trouble Report (FTR) 

An obsolete term; see User Commtmication Form. 

file equation 

A mechanism for specifying the values of file attributes when a program is compiled or 
executed. A file equation implicitly assigns a value to tiie FILECABDS task attribute. 
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file-equate 

To specify the file title and other file parameters that are difierent from the defaults 
provided by the source program. 

FORTRAN 

Formula Translation. A high-level, structured programmiag language intended primarily 
for scientific use. 

FORTRAN?? 

. A version of the FORTRAN language that is compatible with the ANSI X3.9-1978 
standard. 

FTR 

An acronym for the obsolete term Field Trouble Report. See User Commimication Form. 

G 

GIVING clause 

In COBOL, an optional clause in the CALL non-numeric literal statement that specifies 
a variable as the destination for the integer value 

global data item 

A data item, group item, or population item that is not a part of any data set. Global 
data items generally contain information such as control totals, hash totals, and 
populations that apply to the entire databeise. 

group item 

A collection of data items that can be viewed as a single data item 

H 

halt/load 

A system-initialization procedure that temporarily halts the i^stem and loads the master 
control program (MOP) firom a disk to main memory. 

hashing algorithm 

An algorithm used in constructing and maintaining hash tables, which modify record 
to produce tibe addresses of the record k^ in a structure. 

I 

ID 

See identifier. 

identifier (ID) 

(1) A label (2) One node of a file name. 

import 

To bring in firom an outside source and still retain the original significance or fimction. 
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IN LIBRARY statement 

In FORTRAN??, the statement that associates the logical expression name of an entry 
point with the library that is kno\m to the application program through the library 
identifier. 

INCLUDE 

A compiler control option that enables the user to insert an entire file, or sequence range 
within a file, into a program. 

index sequential structure 

A structure that is a collection of tables arranged hierarchically. 

input/output mapping clause 

A clause that can be used with data management operations to assign the value of a 
database item to a program variable (input) and/or to assign the value of a program 
variable to a database item (output). 

inquiry mode 

A database mode in which data can be read but not updated. 

integer 

A whole number, 
internal file name 

The name used to declare a lo^cal file in a program. The internal name of a file is given 
by the value of its INTNAME file attribute. Work Flow Language (WFL) file equation 
statements can reference the Gle by implicitly or explicitly specifying an INTNAME value 
that matches the INTNAME attribute of a file in a program. 

interpretive interface 

A set of conventions for passing information using the DMINTERPRETER library. 

INTNAME 

See internal file name. 

intrinsic 

A system-supplied program routine for common mathematical and other operations 
that is loaded onto the system separately. An intrinsic can be invoked by ihe operating 
system or user programs. 

intrinsic data set 

A data set created by system designers as part of a Data Management System n 
CDMSn) software package, as opposed to a data set created by a user. 

invocation 

(1) The syntax used to initiate execution of software. (2) The act that transfers control 
to the start of a specified procedure, initializes any parameters, and begins the execution 
of the statements of the {M'ocedure. Invocaticxos are of two kinds: entrances and 
initiations. 

invoke 

(1) To cause to be executed. (2) To cause to be brou^t into main storage. 
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item 



A field ia a database record that contains an individual piece of information and can be 
referenced name, 



job 

K 

Eapji 



An independent process. The job of a particular task is the independent process that is 
the eldest ancestor of that task. 



The standard Japanese character set for information exchange. Each Kanji character is 
2 bytes (16 bits) in length and takes two positions on a form image. 



Eaiigi alpha string 

A string, delimited by quotation marks, that is further delimited by a start of Kanji 
(SOK) character (48"2B") and an end of Kanji (EOK) character (48''2C"). 

Eax^ji character literal 

A character string botmded on the left by the separator NC" and on the right by a 
quotation mark C) • The string contains Kanji characters between the be^nning and 
ending quotation marks. 



key field 
key item 



(1) A field used to locate or identify a record in an indexed file. (2) A field in a record 
that is used to sort a file. (3) See o/so key item. 



See key. 

A data item or group item that serves as a retrieval key for a set, subset, or access. 



language extension 

A syntactical addition to a standard language compiler that enables tiie compiler to 
inter&ce directiy with Unisys in*oducts. 

library 

(1) A collection of one or more named routines or library objects that are stored in a file 
and can be accessed by otiier programs. (2) A program that exports otgects for use by 
user programs. 

library directory 

A memory structure associated with a library process stack tiiat describes the objects 
escported by the library process. 
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library identifier 

An internal name \vithin an application program that represents the library code fiOie 
being accessed. 

linear search 

A method for searching a set of information by examining each element of the set one at 
a time. 

link item 

A field that enables one data set record to refer to another. 

literal 

A character string whose value is implied by the ordered set of characters that compose 
the string. 

logical database 

A collection of structm'es declared in the Data and Structure Definition Language 
(DASDL) that provide a view of the database, enforce structure-level security, and 
achieve data independence. When a logical database is declared in DASDL, the data 
sets, sets, subsets, and remaps to be included ui the database are listed. 

logical eiqpression 

In FORTRAN??, a rule for computing a value corresponding to .TRUE, or .FALSE. . 
Logical expressions consist of any valid combination of logical operands, logical operators, 
and parentheses. 

logical function 

In FORTRAN, a function that returns a value of. TRUE, or .FALSE. . 

M 

msgor key 

The first key in a comply k^. 

mamial subset 

A subset that has no condition specifying which data set records are to be included in the 
subset. The user must add and delete manual subset entries, using the INSERT and 
REMOVE statements. 

master 

A data set or record that contains one or more embedded data sets or records. In 
DMSn, synonym for mast^, parent, owner. 

master control program (MCP) 

The central program of tiie A Series operating syst^n. The term applies to any master 
control program that Umsys may release for A Series systems. 

MCP 

See master control program. 



8600 0155-000 



Glossary-13 



Giossaiy 



MCS 

See message control system. 

member 

A record of a data set. 

message control system (MCS) 

A program that controls the flow of messages between terminals, application programs, 
and the operating system. MCS fxmctions can include message routing, access control, 
audit and recovery, system management, and message formatting. 

metatoken 

An item that appears in syntax notation as a variable item, 
minor key 

Any key in a complex key that is not the major (first) key. 
mnemonic 

(1) An abbreviation or acronym that is used to assist the htmaan memory. (2) A 
programmer-supplied word associated with a specific function name. (3) A character or 
group of characters intended to serve as a mnemonic. 

N 

nonkey item 

An item in the data set being indexed that is not a key item in the selected set. 

null string 

An empty or zero-length string. 

null value 

The value contained in an item that does not contain valid information, 
numeric item 

A data item whose description restricts its contents to a value represented by numeric 
characters. 

0 

object code file 

A file produced by a compiler when a program is compiled successfully. The file contains 
instructions in machine-executable object code. 

object time 

In COBOL, the time during which an object program is executed. Synonym for run tiaae, 
^ecution time. 
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OCCURS clause 

In a Data and Structure Definition Language (DASDL) data item declaration, a 
clause that establishes an ordered (subscripted) collection of data items with identical 
attributes. 

ordered 

Pertaining to an item maintained in a user-specified sequence. 

owner 

See master. 

P 

parent 

A process that owns the critical block of a dependent process. If the parent exits 
the critical block before the dependent process terminates, the dependent process is 
discontinued. See o/^o master. 

path 

(1) The route that must be traced from a directory to a subdirectory, or through a series 
of subdirectories, to find a file. (2) A specific location within the logical ordering of a data 
set, set, subset, or access. 

physical database 

An entire database as it is stored on a disk. Whereas a logical database represents only 
parts of a database to be used for limited purposes, a ph^^cal database is an entire 
database. 

population 

For disjoint data sets, the number of records in the data set. For embedded data sets, 
the population is the number of records in the ^bedded data set owned by tiie current 
master. 

Q 

qualification 

The spedfication of the data set that owns an item. Qualificaticm is usua% used when 
several data sets contain an item with the same name. 

quiet point 

A time during which there are no transactions in pn^ess for a database. See also 
syncpoint. 

R 

railroad diagram 

A graphic representation of the syntax of a command or statement. 
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RDS 

See restart data set. 

real item 

A data item that stores signed or unsigned, fractional or whole values in single-precision, 
floating-point form. 

real ntuuber 

Any number, including fractions and whole numbers. 



rebtiild 



In database management, a recovery proces's in which the entire database is loaded 
from one or more sets of dump tapes. The recovery process then applies the audit trail 
after-update record images to move the database forward in time. 



record 



(1) A group of logically related items of data in a file that are treated as a unit. (2) The 
data read from or written to a file in one execution of a read or write statement in a 
program. 

record-type item 

Either of the followii^ a binary integer value used in conjunction with variable-format 
data sets to identify the variable-format part, if any, the record contains; or a control 
item that contains the format number for records in variable-format data sets. 

recovery 

In data management, a procedure that is initiated following a hardware, software, 
or operations failure while the database is in update mode. Recovery backs out any 
partially completed transactions by applying audit-trail images to the database to restore 
it to a consistent state. In addition, recovery passes restart information to the programs 
accessing the database. 



remap 



A logical data set that redefines a physical data set by omitting, reordering, or renaming 
the items. 



remote file 

A file with the KIND attribute specified as BEMOTE. A remote file enables object 
programs to communicate interactively with a terminal 

reorganization 

The process of reordering or reformatting data sets, sets, or subsets. Reorganization can 
restore space in files, reorder data sets for more ^Qdent retrieval, and reformat data set 
records when items are added, deleted, or dianged. 

restart data set (RDS) 

A data set containing restart records that application programs can access to recov^ 
database information after a system failure. 

restart record 

A record containing user-defined information that enables a user program to restart in 
response to a particular condition. 
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result descriptor 

A 48-bit word that is the standard Data Management System 11 (DMSII) exception word. 
A result descriptor includes the exception category and subcategory, and the structure 
number involved. When an exception occurs, bit 0 in the 48-bit word is set to 1. When 
an operation is successful, the 48-bit word contains all zeros. 

rollback 

The recovery of a database or transaction base to a consistent state at an earlier point in 
time. 

RPG 

Report Program Generator. A high-level, commercially oriented programming language 
used most frequently to produce reports based on information derived from data files. 

run time 

The time during which an object code file or user interface system (UIS) is executed. 
Synonym for execution time and, in COBOL, object time. 

nm-time error 

An error occurring during the execution of a program, which causes the sjrstem software 
to terminate execution of that program abnormally. 



savepoint 

An user-determined point in a program that is located between a beginning transaction 
marker and its corresponding end transaction marker. While executing the transaction, 
processing can be specifically backed out to this point. 



schema 



The outline or description of a database. The schema acts as a map for tiie host system 
to use when performing any functions on the database or when accessing the database. 



selection expression 

The entire complement of selection criteria used in a FIND, LOCK, or DELETE 
statement to locate a data set record The definition of a selection expression 
encompasses both the select options (FIBSi; NEXX LASX and PBIOB) and all the 
variations for the key conditions. See a/so condition. 

Semantic Information Manager (SD\I) 

The basis of the InfoExec environment. SIM is a database management system used 
to describe and maintain associations among data means of subdass-superclass 
relationships and linking attributes. 

serial search 

A method for searching a set of information by examining each element of Uie set one at 
a time. 



set 



A file of indexes that refers to all the records of a ^n^e data set. Sets are automatically 
maintained by the system. Sets permit access to the records of a data set in some logical 
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sequence and are normally used to optimize certain types of retrievals of the data set 
records. 

SIM 

See Semantic Information Manager. 

SOK 

See start of Kanji character, 
source file 

(1) A file in which a source program is stored. (2) A file containing instructions written in 
a programming language. 

standard entry point 

In the DMINTERPKETER library, an entry point that performs a function 
corresponding to a function specified in a Data Management System n (DMSII) user 
language statement. 

start of Kanji (SOK) character 

A character that signals the beginning of a Kanji character string. 

string 

A connected sequence or group of characters. 

structure 

A data set, set, subset, access, or remap. 

subitem 

An item that is a member of a group item. 

subscript 

A number that is an index into an array. 

subset 

An index structure that is identical to a set, except that the subset need not contain a 
record for every record of the data set. A set must index every record in its associated 
data set, whereas a subset can index zero, one, several, or all data set records. A 
subset might or might not be automadcalJt^ maintained by Data Managem^t System n 
(DMSn). 

Sfyncpoint 

A point in time when no pr(^ram is in a transaction state. 

syntax 

The rules or grammar of a language. 

T 

TEX. 

See Transaction Formatting Language. 
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timestamp 

An encoded, 48-bit numerical value for the time and date. Various timestamps are 
maintained by the ssrstem for each disk file. Timestamps note the time and date a file 
was created, last altered, and last accessed. 



TITLE 



TPS 



A file attribute whose value is the external name of a file. By default, this value is the 
value of the INTNAME attribute. For a file whose KIND attribute is equal to DISK 
or PACK, the TITLE attribute can be assigned a value of the form <file name > ON 
< family name > ; thus, the values of the TITLE and FILENAME attributes, both of 
which spedfy the external file name, can be different. 



See transaction processing system. 



transaction 

(1) The transfer of one message from a terminal or host program to a receiving host 
program, the processing carried out by the receiving host program, and the return of an 
answer to the sender. (2) In data management, a sequence of operations grouped by a 
user program because the operations constitute a sii^e logical change to the database. 

Transaction Formatting Language (TFL) 

The Unisys language used to write source files that are compiled to produce description 
files for transaction bases. 

transaction point 

A point that is e^Mtljr assigned in a program between a begin transaction statement 
and an end transaction statement so that the programmer is able to cancel or partially 
cancel a transaction that has not yet completed processing. 

transaction processing system (TPS) 

A Unisys system that provides methods for processing a high volimie of trantsactions, 
keeps track of all input transactions that access the database, enables the tiser to batch 
data for later processing, and enables transactions to be processed on a database that 
resides on a remote system. 

transaction state 

The period in a user-language pn^am between a begin transaction operation and an 
end transaction operation. 

u 

UCF 

See Us^ Communication Form, 
unordered 

Beferring to files, data sets, sets, and subsets that are not maintained in a user-specified 
order. 

update 

To delete, insert, or modify information in a database or transaction base. 
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update mode 

A database or file access mode in which data can be inserted, deleted, or modified. 

User Communication Form (UCF) 

A form used by Unisys customers to report problems and express conmients about 
Unisys products to support organizations. 

user work area 

A memory area in,a user program where data records are constructed, accessed, or 
modified. The Accessroutines maintain one user work area for each data set or remap 
invoked by a program. 

USING clause 

In COBOL, an optional clause in the CALL nonnumeric literal statement that identifies 
the parameters being passed to a library entry point. 



utility 

V 

variable 



A systCTi software program that performs commonly used functions. 



An object in a program whose value can be changed during program execution. 



variable format 

A record format that consists of two parts: a fixed part and a variable-format part. A 
single record description exists for the fixed part. The variable-format part can describe 
several variable parts. An individual record is constructed by using the fixed part alone, 
or by joining the fixed part with one of the variable parts. 

variable-f onnat data set 

A data set with records that can have several different formats. AH records in such a 
data set, known as variable-format records, consist of a common fixed part and optionally 
include one of the variable parts declared in the Data and Structure Definition Language 
(DASDL). 

w 

WFL 
WFLjob 



jSee Work Flow Language. 



(1) A Work Flow Language (WFL) program, or the execution of such a program. (2) A 
collection of WFL statem^ts that enable the user to run programs or tasks. 



WFL job deck 

See job. 
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word 

A xmit of computer memory. On A Series systemis, a word consists of 48 bits used for 
storage plus tag bits used to indicate how the word is interpreted 

Work Flow Language (WFL) 

A Unisys language used for constructing jobs that compile or run programs on A Series 
sjrstems. WFL includes variables, egressions, and flow-of-control statements that offer 
the programmer a wide range of capabilities with regard to task control. 



ZIP 



A statement that initiates the Work Flow Language (WFL) compiler. A ZIP is commonly 
used to initiate compilations automatically. 
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finding records ^nx > , 3-28 
GIVING clause, 2-12 
identifying types of exceptions, 5-10 
involdng entry points, 2-11 



invoking the DMINTERPRETER library, 
2-9 

locking records /inx > , 3-33 
locking structtires /inx> , 3-36 
moving character strings to variables, 4r-9 
moviag double-precision values to 

variables, 4-21 
moving Kanji character strings to 

variables, 4-14 
moving numeric values to variables, 4-16 
opening databases, 3-8 
passing parameters, 2-11 
placing double-precision values into data 

items, 4r-46, 4Ht9 
placing numeric values iato data items, 

4-41, 4-44 
placing strings into data items, 4r-34 
placing strings into Kanji alpha items, 4r-39 
programming considerations 
accessing entry points, 1-6, 2-8 
entry point names, 1-6 
re-creatkig records, 3-64 
restricting calls to the Accessroutines, 6-2, 

6-3 

retrieving Boolean or field items, 4-29 
returning exceptions, 5-4 
returning text of exception messages, 6-7 
sample program, C-15 
saving transaction points, 3-52 
securing records ^nx> , 3-41 
securing structures /inx> , 3-44 
setting Boolean values, 4-54 
setting current path yinx> , 3-15 
setting null values, 4-59 
storing records, 3-68 
table df entiy points, 2-8 
unlocking records, 3-19 
imlocking structures, 3-23 
using TITLE attribute, 2-10 
COBOL85 

aborting transactions, 3-49 

accessing entry points, 1-6, 2-8 

accessing library entry points, 2-11 

accessing the interpretive interface, 2-8 

beginning transaction state, 3-47 

CALL statement, 2-11 

canceling transactions to savepoints, 3-55 

CHANGE construct, 2-10 

changing libraries, 2-10 

closing databases, 3-73 

constructing data entry points dynamicaUy, 

4r-6S 
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creating new records, 3-11 

deleting records, 3-60 

ending transaction state, 3-71 

entry points, table of, 2-8 

executing language extensions, 3-78 

exported names of entry points, 2-8 

finding records, 3-28 

GIVING clause, 2-12 

identifying types of exceptions, 5-10 

invoking entry points, 2-11 

invoking the DMINTERPRETER Ubrary, 

2- 9 

locking records, 3-33 

locking structures, 3-36 

moving character strings to variables, 4r-9 

moving double-precision values to 

variables, 4r-21 
moving Kanji character strings to 

variables, 4^14 
moving nimieric values to variables, 4-16 
opening databases, 3-8 
passing parameters, 2-11 
placing double-precision values into data 

items, 4-46, 4-49 
placing numeric values into data items, 

4r-41,4r44 

placing strings into data items, 4-34 
placing strings into Kanji alpha items, 4-39 
programming considerations 

accessing entry points, 1-6, 2-8 

entry point names, 1-6 
re-creating records, 3-64 
restricting calls to the Accessroutines, 6-2, 
6-3 

retrieving Boolean or field items, 4-29 
returning exceptions, 5-4 
returning text of exception messages, 5-7 
saving laransaction points, 3-52 
securing records, 3-41 
securing structures, 3-44 
setting Boolean values, 4-54 
setting current path, 3-15 
setting null values, 4-59 
storing records, 3-68 
table of entry points, 2-8 
unlocking records, 3-19 
unlocking structures, 3-23 
using TITLE attribute, 2-10 
coding of standard enl^ points, sequence, 

3- 1 

COMPACT data set, as entry for 
DATASET-SUBTYPE, 7-4 



compile-time interface, 1-1 
compilers that can use the interpretive 
interface, 1-1 

< condition > 
deleting records, 3-58 
finding records, 3-26 
locking records, 3-31 
securing records, 3-39 

constructing data transfers durii^ program 

execution, 4-60 
copy operations, 3-62 
copying records, through re-creation 

operation, 3-61 
COUNT entry, for ITEM-SUBTYPE, 7-6 
coimt items 

transferring double-precision values to 

variables, 4-21 
transferring values to variables, 4-16 
create operations, 3-9 

< create statement > , executing through 

entry point, 3-75 
creating new records, 3-9 
current paths, setting, 3-13 

D 

DASDL, (See Data Structure and Definition 

Language (DASDL)) 
data items, tables o^ 7-2 
data management statements, executing, 

3-74 

< data request > , constructing transfers 

dynamically, 4-60 

< data set qualified name > 
creating new records, 3-10 
deleting records, 3-58 
findii^ records, 3-26 
freeing data set records, 3-18 
freeii^ structures, 3-21 
lockii^ records, 3-31 
locking structures, 3-35 

moving character strii^ to variables, 4-7 
moving double-precision values to 

variables, 4-22 
moving Kanji character strings to 

variables, 4-12 
moving numeric values to variables, 4r-17 
placing double-predsion values into data 

items, 4-47 
placing nimieric values into data items, 

4r-42 
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placing string into Kanji alpha items, 4-37 

placing strings into data items, 4-32 

re-creating records, 3-62 

retrieving Boolean or field items, 4-27 

securing records, 3-39 

securing structures, 3-43 

setting Boolean values, 4-52 

setting current path, 3-14 

setting null values, 4-57 

storing records, 3-66 
data set records, freeing, 3-17 
< data set > 

locking structures, 3-34 

seciaring structures, 3-42 
data sets 

defining types of in DBSTRUCTURE data 

set, 7-4 
setting current paths, 3-13 
Data Structure and Definition Language 

(DASDL) 
database for sample programs, G-2 
describing the DBSTRUCTUEE data set, 

7-2 

using ZIP, A-5 
data transfer entry points, 4-1 
ALGOLDATA, 4-60 
ALGOLGETBOOLEAN, ^26 
ALGOLGETDOUBLE, ^21 
ALGOLGETKANJI, 4^11 
ALGOLGETREAL, 4r-16 
ALGOLGETSTRING, 4-6 
ALGOLPUTBOOLEAN, 4r-51 
ALGOLPUTDOUBLE, 4-46 
ALGOLPUTKANJI, 4-36 
ALGOLPUTNULL, 4-56 
ALGOLPUTREAL, 4-41 
ALGOLPUTSTRING, 4-31 
DBDATA, 4-60 
DBGETBOOLEAN, 4-26 
DBGETDISPLAX4-6 
DBGETD0UBLE,4-21 
DBGETKANJI, 4-11 
DBGETREAL, 4^16 
DBPUTBOOLEAN, 4-51 
DBPUTDISPLA^4r^l 
DBPUTD0UBLE,4-46 
DBPUTKANJI, 4-36 
DBPUTNULI/mx> , 4-56 
DBPUTREAL,4-41 
exceptions, 4-4 
FORTRAN77DATA, 4-60 
FORTRAN77GETBOOLBAN, 4r.26 



FORTRAN77GETGHARACTER, 4-6 

FORTRAN77GETDOUBLE, 4-21 

FORTRAN77GETKANJI, 4-11 

FORTRAN77GETREAL, 4-16 

FORTRANr77PUTCHARACTER, 4r-31 

FORTRANr77PUTDOUBLE, 446 

FORTRAN77PUTKANJI, 4-36 

FORTRAN77PUTLOGICAL, 4-51 

FORTRAN77PUTNULL, 4r^6 

FORTRAN77PUTREAL, 4r41 

purpose of, 1-4 

table of, 4-1 
data transfer tasks 

performed by entry points to the 

DMINTERPRETER library, 44 
DATA value, as entry for ITEM-KEY-CLASS, 
7-8 

< data-name > , invoking COBOL entry 

points, 2-11 

< data> , constructing transfers dynamically, 

4-61 

DATABASE card, A-15 
dateibase definition for 

sample programs, C-2 
database equation, using, 1-9 

< database name > 
finding records, 3-26 

freeing ^obal data records, 3-18 
lockup records, 3-31 
securing records, 3-39 
storing records, 3-67 

< database statement > , executii^ through 

entry point, 3-74 
database structure, determining, 7-1 
DATABASE/DMINTERPRETER 
ensuring consistency with program 

symbolic, A-4 
generating DMINTERPRETBR library, 
A-1 

use in FORTRAN77, 2-14 
DATABASE/DMINTERPRETER symbolic 
file 

providii^ declarations of library entry 

points, 1-6 
providing eaqported names of library entry 

points, 1-6 
use in ALGOL programs, 2-4 
use in COBOL programs, 2-8 
\2se in FORTRAN77 programs, 2-14 
DATABASE/PROPERTIES, generating 

DMINTERPRETER library, A-1 
databases 
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aborting transactions, 3-48 
beginning transaction state, 3-45 
canceling transactions back to savepoints, 

3-53 
closing, 3-72 
declaring, 2-1 

ending transaction state, 3-69 

invoking, 2-1 

opening, 2-1, 3-6 

saving transaction points, 3-50 
DATAERROR category 

exception and error subcategories, B-4 

major category number, B-2 
DATASET value, as entry for DB-TYPE, 7-3 
DATASET-SUBTYPE item, in 

DBSTRUCTURE data set, 7-4 
DB-ID item, in DBSTRUCTURE data set, 
7-3 

DB-NAME item, in DBSTRUCTURE data 
set, 7-3 

DB-OWNER item, in DBSTRUCTURE data 
set, 7-3 

DB-TYPE item, in DBSTRUCTURE data set, 
7-3 

DB-TYPE of DATASET, DBSTRUCTURE 
items, 7-4 

DB-TYPE of ITEM, DBSTRUCTURE data 

set items, 7-5 
DB-TYPE of LINK, DBSTRUCTURE items, 

7-8 

DB-TYPE of set; DBSTRUCTURE items, 
7-4 

DBABORTTRANSACnON, aborting 

transactions, 3-48 
DBBEGINTRANSACTION, beginning 

transaction state, S-45 
DBCANCELTRPOINT, canceling 

transactions to savepoints, 3-53 
DBCLOSE, closing databases, 3-72 
DBCREATE, creating new records, 3-9 
DBDATA, constructing data entry points 

dynamically, 4-60 
DBDELETE, deleting a record, 3-56 
DBENDTRANSACnON, ending transaction 

state, 3-69 
DBEXCEPnONNAME, identifying types 

CTceptions, 5-8 
DBEXCEPTIONTEXX returning text of 

exception message, 5-5 
DBFIND, finding records, 3-24 
DBFREE, freeing records, 3-17 
DBFREESTR, freeing structures, 3-21 



DBGET entry points, 4-3 
DBGET operations 

constructing data entry points dynamically, 
4-60 

moving character strings to variables, 4-6 
moving double-precision values to 

variables, 4^-21 
moving Kanji strings to variables, 4-11 
moving nvuneric values to variables, 4-16 
retrieving Boolean or field items, 4-26 
using with DBSTRUCTURE data set, 7-1 
DBGETBOOLEAN, retrieving Boolean or 

field items, 4-26 
DBGETDISPLAY, moving character strings 

to variables, 4-6 
DBGETDOUBLE, moving double-precision 

values to variables, 4-21 
DBGETKANJI, retrieving Kanji character 

strings, 4-11 
DBGETREAL, moving numeric values to 

variables, 4-16 
DBLOCK, locking records, 3-29 
DBLOCKSTR, locking structures, 3-34 
DBOPEN, opening a database, 3-6 
DBPUT entry points, 4r-3 
DBPUT operations 

constructing data entry points dynamically, 
4-60 

placing double-precision values into data 

items, 4-46 
placing numeric values into data items, 

4-41 

placing strings into data items, 4-31 
placing strings into Kanji alpha items, 4-36 
setting data items to Boolean values, 4-51 
setting data items to null values, 4r-56 
DBPUTBOOLEAN, setting data items to 

Boolean values, 4-51 
DBPUTDISPLAY; placing strings into data 

items, 4-31 
DBPUTDOUBLE, placing double-precision 

values into data items, 4-46 
DBPUTKANJI, placing strings into Kax^i 

alpha items, 4-36 
DBPUTNULL, setting null values, 4-56 
DBPUTREAL, placing ntmieric values into 

data items, 4-41 
DBRECRBATE, re-creating records, 3-62 
DBSAVETRPOINT; saving transaction 

points, 3-50 
DBSECURE, securing records, 3-37 
DBSECURESTR, securing structures, 0-42 
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DBSET, setting the current path, 3-13 
DBSETLBUT, restricting calls on the 

Accessroutines, 6-1 
DBSTATUS, returning exceptions, M 
DBSTORE, storing records, 3-66 
DBSTRUCTURE data set 

DASDL description, 7-2 

defining access method, 7-5 

generating, 7-1 

generating via BUILDINQ program, 7-1 
items, 7-4 

items for DB-TYPE of DATASET, 7-4 
items for DB-TYPE of ITEM, 7-5 
items for DB-TYPE of LINK, 7-8 
items for DB-TYPE of SET, 7-4 
provided by DMINTEKPRETER library, 
7-1 

types of data sets, 7-4 

types of entities, 7-3 

types of sets, 7-5 

using with ERGO, 7-1 
DBSTRUCTURE data sets 

specifying use through BUILDINQ 
program, A-10 

use with ERGO, A-10 
DBVERB, executing langu£^e extensions, 
3-74 

DEADLOCK categoiy 

exception and error subcategories, B-5 

major category nimiber, B-2 
deadlocks 

exceptions and errors, B-5 
deadly embrace, (See deadlocks) 
dedarmg a DMINTERPRETER library 

in ALGOL programs, 2-2 

in FORTRAN77 programs, 2-13 
declaring a subset of the entry points 

in ALGrOL programs, 2-5 

in FORTRAN77 programs, 2-16 
declaring databases 

purpose of^ 2-1 
declaring entry points, IS 

in ALGOL programs, 2-3 

throt^ procedure dedaratiion, 2-5 
through rdease tape, 2-4 

in FORTRAN77 programs 

throu^ logical functions, 2-16 
throu^ release tape, 2-14 

purpose of, 2-1 
dedarii^ libraiy entry points 

in FORTRAN77 programs, 2-14 
delete operations, 3-56 



deleting data records, 3-56 
deleting records 

before recreating a record, 3-61 
DESCRrPTION/< database name> 

in DMINTERPRETER library, A-1 
determining access mode, in BUILDINQ 

program, A-11 
DIRECT data set, as entry for 

DATASET-SUBTYPE, 7-4 
DIRECT value 

as entry for SET-SEARCH-METHOD, 7-5 
< direction > 

deleting records, 3-57 

finding a record, 3-25 

locking records, 3-30 

securing records, 3-38 
DMIDIRECTORY/ < database name > 

ensuring consistency with program 
symbolic, A-4 

generating DMINTERPRETER library, 
A-1 

DMINTERPRETER card, A-15 
DMINTERPRETER library 

attribute setting entry points, 6-1 

BUILDINQ program, relationship to, A-1 

data transfer entry points, 4-3 

database equation, using, 1-9 

DBGET entry points, 4-3 

DBPUT entry points, 4-3 

declaring, 2-1 

exception handling entry points, 5-1 
files produced when generating^ A-1 
files used to generate, A-1 
generating, 1-4, A-1 

from remote terminal, A-5 

from WFL job deck, A-15 

using NOZIP value, A-18 

using ZIE^ A-5 
invoking, 2-1 

providing DBSTRUCTURE data set, 7-1 

purpose o^ 1-4 

standard entry points, 3-1 

structure switching, 1-8 

tasks performed fay entry points 

attribute setting, 6-1 

data transfer, 4-4 

exception handling, 5-1 
types of entiy pdnts, 1-4 
use of global items, 1-9 
DMINTERPRETER library entry points 
declaring, 2-1 

guidelines for sequencing entry points, 1-8 
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invoking, 2-1 

naming and renaming, 1-6 

returning exceptions, 1-7 

types oi, 1-4 

using parameters, 1-7 
DMINTERPKETER/ < database name > , 

generating DMINTERPRETER, A-1 
DMSn application program interfaces, 1-1 
DMSn Kbraries, using, 1-4 
DMSUPPORT library 

purpose of, 1-4 

use by exception handling entry points, 
1-7 

use in exceptions, 5-1 
DUPLICATES category 

exception and error subcategories, B-5 

major category number, B-2 
duplicating records, 3-61 



E 

< EBCDIC string> 

declaring DMINTERPRETER library in 
ALGOL, 2-3 

declaring entry points, 2-6 
EBCDIC strings, using in DBSTRUCTURE 

data set, 7-8 
empty string 

creating new records, 3-10 

re-creating records, 3-62 
end transaction operations, 3-69 

programming con^deration, 1-0 
ending transaction state, 3-69 
ENDING value, in setting current path, 3-14 
entering compilation queue, in BUILDINQ 

program, A-12 
entering DMINTERPRETER code ffle name, 

in BUILDINQ program, A-12 
entering the name of a logical database, in 

BUILDINQ program, A-11 
entering transaction state, 3-45 
entities, defining types of in 

DBSTRUCTURE data set, 7-3 
entry p<nnt declarations 

in ALGOL programs, 2-3 

in COBOL programs, 2-11 

in FORTRAN77 programs, 2-14 
entry points 

ALGOL, listing of; 2-4 

attribute setting, 6-1 

COBOL, listing of, 2-8 



coding sequence, 3-1 

constructing transfers during program 

execution, 4-60 
data transfer, 4r-l, 4-4 
DBGET, 4-3 
DBPUT, 4-3 
declaring, 2-1 

declaring in ALGOL programs, 2-3, 2-7 
declaring in FORTRAN77 programs, 2-14, 
2-18 

exception handling, 5-1 
exporting, 1-4 

FORTRAN77, Usting of, 2-14 
guidelines for sequencing entry points, 1-8 
identifying types of exceptions, 5-8 
importing, 1-4: 
invoking, 2-1 

invoking in ALGOL programs, 2-7 
invoking in COBOL programs, 2-11 
invoking in FORTRAN77 programs, 2-18 
moving character strings to variables, 4-6 
moving data in and out of a user work 

area, 4r-3 
moving double-precision values to 

variables, 4r-21 
moving nimieric values to variables, 4r-16 
placing double-precision values into data 

items, 4-46 
placing ntimeric values into data items, 

placing strings into data items, 4-31 
placing strings into Kanji alpha items, 4-36 
restricting calls to the Accessroutines, 6-2 
retrieving Boolean values, 4r-26 
retrieving Kanji alpha character strings, 
4^-11 

returning exceptions, 1-7, 5-3 

returnii^ text of exception messages, 5-5 

setting data items to Boolean values, 4r-51 

setting data items to null values, 4r^6 

standard, 3-1 

types of, 1-4 

using parameters, 1-7 

using with DBSTRUCTURE data set, 7-1 
ERGO, (See Extended Retrieval with 

Graphic Output) 
error handling in int^retive interface, 5-1 
errors 

major cat^ories by number, B-2 
subcategories, B-2 
examples 

aborting transactions 
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ALGOL, 3-49 

COBOL, 3-49 

FORTRAN??, 3-49 
begiiming transaction state 

ALGOL, 3-i6 

COBOL, 3-4? 

FORTRAN??, 3-4? 
canceling transactions to savepoints 

ALGOL, 3-54 

COBOL, 3-55 

FORTRAN??, 3-55 
dosing databases 

ALGOL, 3-?2 

COBOL, 3-?3 

FORTRAN??, 3-?3 
constructing data entry points dynamicaUy 

ALGOL, 4^62 

COBOL, 4-63 

FORTRAN??, 4-63 
creating new records 

ALGOL, 3-11 

COBOL, 3-11 

FORTRAN??, 3-12 
declaring library entry point 

ALGOL, 2-? 

FORTRAN??, 2-18 
deleting records 

ALGOL, 3-59 

COBOL, 3-60 

FORTRAN??, 3-60 
ending transaction state 

ALGOL, 3-?0 

COBOL, 3-71 

FORTRAN??, 3-?l 
executing language extensions 

ALGOL, 3-77 

COBOL, 3-78 

FORTRAN??, 3-79 
finding records 

ALGOL, 3-27 

COBOL, 3-28 

FORTRAN??, 3-28 
identifying types of exceptions 

ALGOL, 5-9 

COBOL, 5-10 

FORTRAN??, 5-10 
invoking an entry point 

ALGOL, 2-7 

COBOL, 2-12 

FORTAN77, 2-18 
linking to a DMINTERPRETER library 

ALGOL, 2-3 



COBOL, 2-10 

FORTRAN??, 2-14 
locking records 

ALGOL, 3-32 

COBOL, 3-33 

FORTRAN??, 3-33 
locking structures 

ALGOL, 3-35 

COBOL, 3-36 

FORTRAN??, 3-36 
moving character strings to variables 

ALGOL, 4-8 

COBOL, 4-9 

FORTRAN??, 4-10 
moving double-precision values to variables 

ALGOL, 4-23 

COBOL, 4-24 

FORTRAN??, 4r-25 
moving Kanji character strings to variables 

ALGOL, 4r-13 

COBOL, 4-14 

FORTRAN??, 4-15 
moving numeric values to variables 

ALGOL, 4^19 

COBOL, ^20 

FORTRAN??, 4-20 
opening databases 

ALGOL, 3-7 

COBOL, 3-8 

FORTRAN??, 3-8 
placing double-precision into data items 

ALGOL, 4r49 

COBOL, 4-49 
placing double-precision values into data 
items 

FORTRAN77,4r^0 
placing ntmieric values into data items 

ALGOL, 4-44 

C0B0L,4r44 

FORTRAN??, 4r-45 
placing strings into data items 

ALGOL, 4^-34 

COBOL, 4-34 

FORTRAN77,^5 
pladng strix^ into Kanji alpha items 

ALGOL, 4-39 

COBOL, 4-39 

FORTRAN??, 4-40 
re-creating records 

ALGOL, 3-64 

COBOL, 3-64 

FORTRAN??, 3-65 
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restricting calls to the Accessrout ines 

ALGOL, 6-3 

COBOL, 6-3 

FORTRAN??, 6-4 
retrieving Boolean or field items 

ALGOL, 4-28 

COBOL, 4-29 

FORTRAN??, 4-30 
returning exceptions 

ALGOL, 5-4 

COBOL, 5-4 

FORTRAN??, 5-4 
returning text of exception messages 

ALGOL, 5-6 

COBOL, 5-? 

FORTRAN??, 5-7 
saving transaction points 

ALGOL, 3-51 

COBOL, 3-52 

FORTRAN??, 3-52 
securing records 

ALGOL, 3-40 

COBOL, 3-41 

FORTRAN??, 3-41 
securing structures 

ALGOL, 3^3 

COBOL, 3-44 

FORTRAN??, 3-44 
setting Boolean values 

ALGOL, 4-53 

COBOL, 4r-54 

FORTRAN??, 4-55 
setting current path. 

ALGOL, 3-15 

COBOL, 3-15 
setting null values 

ALGOL, 4-58 

COBOL, 4r-59 

FORTRAN??, 4-59 
storing records 

ALGOL, 3-67 

COBOL, a-68 

FORTRAN??, 3-68 
unlocking records 

ALGOL, 3-19 

COBOL, a-19 

FORTRAN??, 3-20 
unlocking structures 

ALGOL, 3-22 

COBOL, 3-23 

FORTRAN??, 3-23 



8600 0155-000 



using a WFL deck to generate the 

DMINTERPRETER library, A-16 
exception categories, 5-8 
exception handling 

category of exception, 5-8 

in ALGOL programs, 2-7 

in COBOL programs, 2-12 

in FORTRAN?? programs, 2-18 

returning exception result, 5-3 

text of exception message, 5-5 

using the interpretive interface, 5-1 
exception handling entry points, 5-1 

algolexceptionname, 5-8 
algolexceptiontext; 5-5 
algolstatus, 5-3 

DBEXCEPTIONNAME, 5-8 
DBEXCEPTIONTEXT, 5-5 
DBSTATUS, 5-3 

F0RTRAN77EXCEPTI0NNAME, 5-8 
FORTRAN77EXCEPTIONTEXT, 5-5 
FORTRAN77STATUS, 5-3 
purpose of, 1-4 
table of, 5-1 
exception handling tasks, performed by entry 
points, 5-1 

exception message, in interpretive interface, 
5-5 

exception word, returned through entry 

point, 5-3 
exceptions 

major categories by number, B-2 

subcategories, B-2 
executing language extensions, 3-74 
explicitly freeing 

records, 3-1? 

structures, 3-21 
exported names 

in ALGOL programs, 2-4 

in COBOL programs, 2-8 

in FORTRAN?? programs, 2-14 

renaming, 1-6 
exporting entry points, 1-4 

renaming, 1-6 
< expression > 

placing double-precision values into data 
items, 4-48 

placing numeric values into data items, 
4-43 

placing values into character strings, 4r-33 
placing values into Kanji strings, 4r-38 
setting Boolean values, 4-53 
Extended Retrieval witii Graphic Output 
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using DBSTRUCTURE data set, 7-1, A-10 



F 

FATALERROR category 

exception and error subcategories, B-6 

major category number, B-2 
FTBLD entry, for ITEM-SUBTYPE, 7-6 
field items 

retrieving Boolean values, 4-26 

transferring double-predsion values to 
variables, 4-21 

transferring values to variables, 4^16 
find operations, 3-24 

restricting linear search, 6-1 

using DBSTRUCTURE data set, 7-1 
finding records, 3-24 

FINDLIMIT, restricting linear searches, 6-1 

FIRST, as direction for 
deleting records, 3-67 
locking records, 3-30 
retrieving records, 3-25 
securing records, 3-38 

fixed-format record 

creating new records, 3-10 
recreating records, 3-63 

FORTRAN77 

aborting transactions, 3-49 
accessing entry points, 1-5, 2-12 
accessing library entry points, 2-14 
accessing the interpretive interface, 2-12 
ACTUALNAME clause, using, 2-17 
beginning transaction state, 3-47 
canceling transactions to savepoints, 3-55 
changing libraries, 2-13 
closing databases, 3-73 
constructing data ^try points dynamically, 
4-63 

creating new records, 3-12 
declaring entry points, 2-14 
declaring the DMINTERPRETER library, 
2-13 

deleting records, 3-60 
ending transaction state, 3-71 
entry points, table of; 2-14 
exception handling, 2-18 
executing langu^e extensions, 3-79 
exported names of entry points, 2-14 
finding records, 3-28 
identifying types of exceptions, 5-10 
invoking entry points, 2-18 



LIBRARY statement (declaration), 2-13 

locking records, 3-33 

locking structures, 3-36 

moving character strings to variables, 4-10 

moving double-precision values to 

variables, 4-25 
moving Eanji character strings to 

variables, 4-15 
moving numeric values to variables, 4r-20 
opening databases, 3-8 
placing double-precision values into data 

items, 4-50 
placing numeric values into data items, 

4-45 

placing strings into data items, 4-35 
placing strings into Kanji alpha items, 4-40 
programming considerations 

accessing entry points, 1-5, 2-12 

entry point names, 1-6 
re-creating records, 3-65 
renaming exported entry points, 2-14 
restricting calls to the Accessroutines, 6-2, 
6-4 

retrieving Boolean or field items, 4r-30 
returning exceptions, 5-4 
returning text of exception message, 6-7 
saving transaction points, 3-52 
securing records, 3-41 
securing structures, 3-44 
setting Boolean values, 4-65 
setting current path, 3-16 
setting nuU values, 4-^9 
storing records, 3-68 
table of entry points, 2-14 
unlocking records, 3-20 
unlocking structures, 3-23 
iiskig TITLE attribute, 2-13 
$INCLUDE compiler control option, use 
of, 2-14 

FORTRAN77 sample program, C-25 
FORTRAN77ABORTTRANSACTION, 

aborting transactions, 3-48 
FORTRAN77BEGINTRANSACTION, 

beginning transaction state, 3-45 
FORTRAN77CANCELTRPOINT, canceling 

transaction to savepoint, 3-53 
FORTRAN77CLOSE, closing databases, 

3-72, 3-73 

FORTRAN77CREATE, creating new records, 

3-9 

FORTRAN77DATA, constructing data entry 
points dynamical^, 4-60 
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FORTRAN77DELETE, deleting a record, 
3-56 

FORTRAN77ENDTRANSACTION, ending 

transaction state, 3-69 
FORTRAN77EXCEPTIONNAME, 

identifying types of exceptions, 5-8 
FORTRAN77EXCEPTIONTEXT, returning 

text of exception message, 5-5 
FORTRAN77FIND, finding records, 3-24 
FORTRAN77FREE, freeing records, 3-17 
FORTRAN77FREESTR, freeing structures, 

3-21 

FORTRAN77GETBOOLEAN, retrieving 

Boolean or field items, 4-26 
FORTRAN77GETCHARACTER, moving 

character string to variable, 4-6 
FORTRAN77GETDOUBLE, moving double 

precision to a variable, 4-21 
FORTRAN77GETREAL, moving numeric 

values to variables, 4-16 
FORTRAN77KANJ1, retrieving Kanji 

character strings, 4^11 
FORTRAN77LOCK, locking records, 3-29 
FORTRAN77LOCKSTR, locking structures, 

3- 34 

FORTRAN770PEN, opening a database, 3-6 
FORTRAN77PUTGHARACTER, placing 

strings into data items, 4r-31 
FORTRAN77PUTDOUBLE 

placing double-precision values into data 

items, 4r46 

FORTRAN77PUTKANJI, placing strings into 

Kanji alpha items, 4^36 
FORTRAN77PUTLOGICAL, setting data 

items to Boolean values, 4-51 
FORTRAN77PUTNULL, setting null values, 

4- 56 

FORTRAN77PUTREAL, placing nimieric 

values into data items, 4-41 
FORTRAN77RECREATE, re-creating 

records, 3-62 
FORTRAN77SAVETRPOINT , saving 

transaction points, 3-50 
FORTRAN77SECURE, securing records, 

3-37 

FORTRAN77SECURESTR, securing 

structures, 3-42 
FORTRAN77SEX setting the current path, 

3-13 

FORTRAN77SETLIMn; restricting caUs to 
Accessroutines, 6-1 



FORTRAN77STATUS, returning exceptions, 
5-3 

FORTRAN77STORE, storing records, 3-66 
FORTRAN77VERB, executing language 

extensions, 3-74 
free operations, 3-17, 3-21 
freeii^ 

records, 3-17 

structures, 3-21 

G 

generating a DMINTERPRETER library, A-1 
ensuring consistency, A-4 
fiOLes used, A-1 

from remote terminals, A-5, A-13 
generating the DBSTRUCTURE data set, 
7-1 

getting field items, 4-26 

GIVING clause, supplying parameters for 

COBOL results, 2-12 
global data records 
deleting, 3-56 
freeing, 3-17 
GLOBAL data set, as entry for 

DATASET-SUBTYPE, 7-4 
global data, in DBSTRUCTURE data set, 7-4 
global items, in DMINTERPRETER library 

stack, 1-9 

GROUP entry, for ITEM-SUBTYPE, 7-6 

group items 

moving character strings to variables, 4-6 
placing strings into data items, 4r-31 

group keys, in DBSTRUCTURE data set, 7-3 

H 

HASH value, as entiy for 

SET-SEARCH-METHOD, 7-^ 
< hyphen name > 
moving character strings to variables, 4r-7 
moving double-precision value to a 

variable, 4r-23 
movii^ Kanji character strings to 

variables, 4^12 
moving nimieric values to variables, 4-18 
pkudi^ double-precision values into data 

items, 4-48 
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placing numeric values into data items, 
4-43 

placing strings into data items, 4-32 
placing strings into Kanji alpha items, 4-37 
retrieving Boolean or field items, 4-28 
setting Boolean values, 4-52 
setting null values, 4-57 



I 

< identifier > 

declaring DMINTERPEETER library in 

ALGOL, 2-3 
invoking DMINTERPEETER library in 
COBOL, 2-10 
identifjnng tjrpes of exceptions, 5-8 
implicitly freeing 
records, 3-17 
structiires, 3-21 
importing entry points, 1-4 

< index set qualified name > 
finding records, 3-26 
locking records, 3-31 
securing records, 3-39 
setting current path, 3-14 

index sets 

finding records, 3-26 

locking records, 3-31 

securing records, 3-39 

setting current paths, 3-13 
initiating the BUILDINQ program, A-5 
inquiry access, 3-6 

INQUIRY value, in opening databases, 3-7 
<integer> 
creating new records, 3-10 
moving character strings to variables, 4-7 
moving double-precision values to 

variables, 4-22 
moving Kanji character strings to 

variables, 4-12 
moving numeric values to variables, 4-18 
placing double-precision values into data 

items, 4-47 
placing numeric values into data items, 

4-42 

placing strings into data items, 4-32 

placing strings into Kanji alpha items, 4-37 

re-creating records, 3-^ 

retrieving Boolean or field items, 4r-27 

setting Boolean values, 4-52 

setting nuU values, 4-57 



rNTEGRITYERROR category 

exception and error subcategories, B-6 

msyor cat^ory number, B-2 
interspersing consecutive calls on structures, 
1-8 

INTLIBERROR 

messages specific to interpretive interface, 
5-1 

INTLIBERROR category 

exception and error subcategories, B-7 

major category number, B-2 
mUSE category 

exception and error subcategories, B-8 

msgor category number, B-2 
invoking databases, purpose of, 2-1 
invoking DMINTERPRETER library 

in COBOL, 2-9 
invoking entry points 

in ALGOL programs, 2-7 

in COBOL programs, 2-11 

in FORTRAN77 programs, 2-18 

purpose of, 2-1 
lOERROR category 

exception and error subcategories, B-9 

major category number, B-2 
< item name > 

moving character strings to variables, 4-7 

moving double-precision values to 
variables, 4-22 

moving Kanji charact^ strings to 
variables, 4-12 

moving numeric values to variables, 4-18 

placing double-precision values into data 
items, 4-47 

placing numeric values into data items, 

4r-42 

placing strings into data items, 4-32 
placing strings into Kanji alpha items, 4-37 
retrieving Boolean or field items, 4r-27 
setting Boolean values, 4-52 
setting null values, 4-57 
ITEM value, as entry for DB-TYPE, 7-3 . 
ITEM-KEY-CLASS item, in 

DBSTRUCTURE data set, 7-8 
ITEM-OCCURS item, in DBSTRUCTURE 

data set, 7-6 
ITEM-OWNER-GROUP item, in 

DBSTRUCTURE data set, 7-7 
riEM-RECORD-TYPE item, in 

DBSTRUCTURE data set, 7-8 
ITEM-REQUIRED item, in DBSTRUCTURE 
data set, 7-7 



lndex-14 - 



8600 0155-000 



Index 



ITEM-SCALE-FACTOR item, in 

DBSTRUCTUKE data set, 7-7 
ITEM-SIGNED item, in DBSTRUCTUEE 

data set, 7-7 
ITEM-SIZE item, in DBSTRUCTURE data 

set, 7-7 
ITEM-SUBSCRIPTS item, in 

DBSTRUCTURE data set, 7-6 
rrEM-SUBTYPE item, in DBSTRUCTURE 

data set, 7-6 
ITEM-USAGE item, in DBSTRUCTURE 

data set, 7-8 
items in DBSTRUCTURE data set, 7-^ 



K 

Kanji strings 

moving to variables, 4-11 

placing strings into alpha items, 4r-36 

using in DBSTRUCTURE data set, 7-8 
KEYCHANGED category 

exception and error subcategories, B-10 

msgor category number, B-2 

L 

language extensions, executing, 3-75 
LAST, as direction for 

deleting records, 3-57 

locking records, 3-30 

retrieving records, 3-25 

securing records, 3-38 
LDBNAMEcard,A-15 
leaving transaction state, 3-69 
libraries, declaring and invoking, 2-1 
library declaration, ALGOL, 2-2 

< library declaration > , declaring 

DMINTERPRETER in ALGOL, 2-2 

< library ^try point declaration > 
in ALGOL, 2-6 
inFORTRAN77,2-16 

Ubrary generation, DMINTERPRETER, A-1 
<libraiyID> 
dedarii^ ALGOL entry points, 2-6 
declaring DMINTERPRETER library in 

ALGOL, 2-2 
declaring DMINTERPRETER library in 

FORTRAN77, 2-13 
declaring FORTRAN77 entry points, 2-17 



invoking COBOL entry points, 2-11 
invoking DMINTERPRETER library in 
COBOL, 2-10 
LIBRARY statement, in FORTRAN77, 2-13 

< library statement > , declaring 

DMINTERPRETER library, 2-13 

< limit type > , specifying type of linear 

search, 6-1 

< limit value > , specifying length of linear 

search, 6-1 
LIMITERROR category 

exception and error subcategories, B-10 
major category nimiber, B-2 
limitii^ find, lock, and secure operations, &-1 
limiting ntmiber of calls to Accessroutines, 
&-1 

linear searches, restricting, 6-1 
LINEAR value, as entry for 

SET-SEARCH-METHOD, 7-5 
LINK value, as entry for DB-TYPE, 7-3 
LINK-OCCURS item, in DBSTRUCTURE 

data set, 7-8 
LINK-TO-DATASET item, in 

DBSTRUCTURE data set, 7-8 

<link> 

deleting records, 3-58 

finding records, 3-27 

locking records, 3-31 

securing records, 3-39 
lock operations 

interpretive interface, 3-29 

restricting linear search, 6-1 
lock structure operations 

interpretive interface, 3-34 
locking 

records, 3-29 

structures, 3-34 

< logical expresdon> , setting Boolean values 

inFORTRAN77,4r-53 

< logical function name > , invoking 

FORTRAN77 entiy points, 2-16 
LOGICAL FUNCTION, declaring 

FORTRAN77 entry points, 2-16 
logical functions, declaring FORTRAN77 

entry points, 2-16 

M 

main interpretive interface software 
components, 1-2 
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major categories for exceptions and errors, 

table of, B-2 
MAJOR value, as entry for 

ITEM-KEY-CLASS, 7-8 
manipulating databases, usiag standard entry 

points, 3-1 
MINOR value, as entry for 

ITEM-KBY-CLASS, 7-8 
modifying 

nonrequired items, 3-61 
required items, 3-61 
moving 

character strings to variables, 4-6 
data in and out of a DMSII user work area, 
4-3 

double-precision values to variables, 4-21 
numeric value to variables 

double-precision, 4r-21 

single-precision, 4-16 



N 

NEXT, as direction for 

deleting records, 3-57 

locking records, 3-30 

retrieving records, 3-25 

securing records, 3-38 
NOAUDrr value 

setting when beginning transaction state, 
3-46 

setting when ending transaction state, 
3-69 

NONE value, as entry for 

ITEM-KEY-CLASS, 7-8 . 
< nonnumeric literal > , invoking 

DMINTERPRETERHbraiy, 2-10 
nonrequired items, modifying, 3-61 
NORECORD category 

exception and error subcategories, B-10 

major category number, B-2 
NOTFOUND category 

exception and error subcategories, B-11 

major category number, B-2 
NOTLOCKED category 

exception and error subcategories, B-12 

major category number, B-2 
NOUPDATE card, A-16 
NOZIP value, generating the 

DMINTERPRETER library, A-13 
null values, setting, 4r-56 
NUMBER entry, for ITEM-SUBTYPE, 7-6 



nimiber items 

in DBSTRUCTURE data set, 7-7 
signed number in DBSTRUCTURE data 
set, 7-7 

transferring double-precision values to 

variables, 4-21 
transferring values to variables, 4-16 

o 

OCCURS clause, in DBSTRUCTURE data 

set, 7-6, 7-8 
open disposition, setting access mode for open 

operation, 3-6 
< open disposition > , in opening DMSII 

database, 3-7 
open operations, 3-6 
OPENERROR category 

exception and error subcategories, B-12 
major category nimiber, B-2 
opening databases, 3-6 
accessing a database, 2-1 
UPDATE versus INQUIRY access mode, 
3-7 

operations 

aborting transactions, 3-48, 3-53 
begiimii^ transaction state, 3-45 
canceling transactions points, 3-53 
closing DMSn databases, 3-72 
creating new records, 3-9 
DBGET 

constructing data entry points 
ctynandcaUy, 4r-60 

moving character strings to variables, 

4r-6 

moving double-precision values to 

variables, 4r-21 
moving Kanji strings to variables, 4-11 
moving nimieric values to variables, 

4^16 

retrieving Boolean or field items, 4r-26 
DBPUT 

constructing data entry points 

dynamically, 4rS0 
pladng double-predsion values into data 

items, 4r-46 
placing numeric values into data items, 

4r4l 

pladng strings into data items, 4r-31 
placing strings into Kanji alpha items, 

4r-36 
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setting data items to Boolean values, 

4r-51 

setting data items to null values, 4-56 
deleting data records, 3-56 
ending transaction state, 3-69 
entering transaction state, 3-45 
executing language extensions, 3-74 
finding records, 3-24 
freeing records, 3-17 
freeing structures, 3-21 
locking records, 3-29 
locking structures, 3-34 
opening databases, 3-6 
re-creating records, 3-61 
reserving space for new records, 3-9 
restricting number of calls to 

Accessroutines, 6-1 
returning exception word, 5-3 
returning text of exception message, 5-5 
returning type of exception message, 5-8 
saving transaction points, 3-50 
securing records, 3-37 
securing structures, 3-42 
setting the current path, 3-13 
storing records, 3-66 

P 

< parameter > , invoking FORTRAN77 entry 

points, 2-16 
parameters, using in entry points, 1-7 
passing parameters, in COBOL languages, 

2-11 

placing 

double-precision values into data items, 

4r-46 

numeric values into data items, 4-41 
strings into data items, 4-31 
strings into Kanji alpha items, 4r-36 
POPULATION entiy, for ITEM-SUBTYPE, 
7-6 

poptilation items 

transferring double-precision values to 
variables, 4-21 

transferring values to variables, 4-16 
PRIOB, as direction for 

deleting records, 3-57 

locking records, 3-30 

retrieving records, 3-25 

securing records, 3-38 



procedure declaration, for ALGOL entry 
points, 2-5, 2-^ 

< procedure heading > , declaring ALGOL 

entry points, 2-6 

< procedure ID > 

declaring ALGOL entry points, 2-6 
invoking COBOL entry points, 2-11 

progreimming considerations and guidelines, 
1-7, 2-1 
for standard entry points, 3-3 
reducing run-time overhead, 1-8 
sequencing entry points, 1-8 

protected state, 3-45 



Q 

QUEUE card 

remote generation of DMINTERPRETER, 
A-14 

WFL generation of DMINTERPRETER, 
A-15 



R 

Railroad diagrams, explanation of, D-1 
RANDOM data set, as entry for 

DATASET-SUBTYPE, 7-4 
random retrieval, 3-24 
re-create operations, 3-62 
re-creating records, 3-61 
READONLY category 

exception and error subcategories, B-15 

major category number, B-2 
REAL entry, for ITEM-SUBTYPE, 7-6 
real items 

in DBSTRUCIURE data set, 7-7 

transferring double-precision values to 
variables, 4r-21 

transferring values to variables, 4-16 

< record statement > , executing through 

entry point, 3-75 

< record type > 

creatii^ new records, 3-10 

re-creating records, 3-63 
record-type items 

toansferring double-precision values to 
variables, 4-21 

transferring values to variables, 4-16 
records 
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creating, 3-9 

deleting, 3-56 

finding, 3-24 

freeing, 3-17 

locking, 3-29 

re-creating, 3-61 

securing, 3-37 

storing, 3-66 
RECOVER option, use of NOZEP value, A-13 
reducing overhead guidelines, 1-8 
release tape, declaring entry points for 

ALGOL programs, 2-4 

FORTRAN77 programs, 2-14 

supported COBOL languages, 2-8 
releasing 

records, 3-17 

structures, 3-21 
remote generation of DMINTERPRETER 

library, A-5, A-13 
remote terminal, generating 

DMINTERPRETER Ubraiy, A-5, 
A— 13 

renaming entry points, 1-6 
in ALGOL, 2-4, 2-6 
in FORTRAN77, 2-14, 2-17 
renaming hyphenated database names, in 

BUILDINQ program, A-11 
reporting errors, using DMSUPPORT library, 
1-4 

required items 

explanation of, 7-2 

modifying, 3-61 
reserving space for new records, 3-9 
RESTART data set, as entry for 

DATASET-SUBTYPE, 7-4 
restart data sets 

when beginning transaction state, 3-45 

when ending transaction state, 3-69 
restricting 

calls to the Accessroutiaes, 6-1 

linear searches, 6-1 

mmiber of calls to the Accessroutines, 6-1 
result descriptor, as DMSn exceptioD. word, 

5-1 
retrieving 

Boolean items, 4r-26 

field items, 4-26 

Kanji alpha character strings, 4-11 
retumix^ 

exception word operations, 5-3 

exceptions, 1-7, 5-3 

text of exception messages, 5-5 



type of exception, 5-8 
run-time interface, 1-1 
run-tune libraries, purpose of, 1-4 



s 

sample programs 

ALGOL, C-5 

COBOL74, C-15 

DASDL source for, C-2 

FORTRAN77, C-25 
save transaction point operations, 3-50 
<savepoiQt> 

canceling transactions to savepoints, 3-53 

saving transaction points, 3-50 
saving transaction points, 3-50 

< search statement > , executing through 

entry point, 3-76 
secure operations 

interpretive interface, 3-37 

restricting liaear search, 6-1 
secure structure operations 

interpretive interface, 3-42 
securing 

records, 3-37 

structures, 3-42 
SECURTTYERROR category 

exception and error subcategories, B-16 

major category number, B-2 
selecting data sets, in BUILDINQ program, 
A-10 

selecting the database, in BUILDINQ 

program, A-5 
selecting view of database, in BUILDINQ 

program, A-6 

< selection egression > 
deleting records, 3-58 
findk^ records, 3-27 
lockjng records, 8-31 
securing records, 3-39 

sequence of interpretive interface tasks, 

guidelines, 1-8 
sequ^ce range in 

DATABASE/DMINTERPRETER 
for ALGOL declarations and entry points, 

2-4 

for FORTRAN77 declarations and entry 
points, 2-14 
sequential retrieval, 3-24 
set operations, 3-13 

using with DBSTRUCTURE data set, 7-1 
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< set statement > , executing through entry 

point, 3-75 
SET value , as entry for DB-TYPE, 7-3 
SET value, as entry for SET-SUBTYPE, 7-5 
SET-SEARCH-METHOD item, in 

DBSTRUCTURE data set, 7-5 
SET-SPANS-DATASET item, in 

DBSTRUCTURE data set, 7-5 
SET-SUBTYPE item, in DBSTRUCTURE 

data set, 7-5 
sets, defining types of in DBSTRUCTURE 

data set, 7-5 

setting 

Boolean values, 4-51 

current paths, 3-13 

data items to nuU values, 4r-56 

variables to a character string, 6-1 
STANDARD data set, as entry for 
DATASET-SUBTYPE, 7-4 
standard entry points, 3-1 

ALGOLABORTTRANSACTION, 3-48 

ALGOLBEGINTRANSACTION, 3-45 

ALGOLCANCELTRPOINT, 3-53 

ALGOLCLOSB, 3-72 

ALGOLCREATE, 3-9 

ALGOLDELETE, 3-56 

ALGOLENDTRANSACnON, 3-69 

ALGOLFIND, 3-24 

ALGOLFREE, 3-17 

ALGOLFREESTR, 3-21 

ALGOLLOCK, 3-29 

ALGOLLOCKSTR, 3-34 

ALGOLOPEN, 3-6 

ALGOLRECREATE, 3-62 

ALGOLSAVETRPOINT, 3-50 

ALGOLSECURE, 3-37 

ALGOLSECURESTR, 3-42 

ALGOLSET, 3-13 

ALGOLSTORE, 3-66 

ALGOLVERB, 3-74 

DBABORTTRANSACnON, 3-48 

DBBEGINTRANSACTION, 3-45 

DBCANCELTRPOINT, 3-53 

DBCLOSE, 3-72, 3-73 

DBCREATE, 3-9 

DBDELETE, 3-56 

DBENDTRANSACnON, 3-69 

DBFIND, 3-24 

DBFREE, 3-17 

DBFREESTR, 3-21 

DBLOCK, 3-2Q 

DBLOCKSTR, 3-34 



DBOPEN, 3-6 
DBRECREATE, 3-62 
DBSAVETRPOINT, 3-50 
DBSECURE, 3-37 
DBSECURESTR, 3^2 
DBSET, 3-13 
DBSTORE, 3-66 
DBVERB, 3-74 

FORTRAN77ABORTTRANSACTION, 
3-48 

FORTRAN77BEGINTRANSACTION, 
3-45 

FORTRAN77CANCELTRPOINT, 3-53 
FORTRAN77CLOSE, 3-72, 3-73 
FORTRAN77CREATE, 3-9 
FORTRAN77DELETE, 3-56 
FORTRAN77ENDTRANSACTION, 3-69 
FORTRAN77FIND, 3-24 
FORTRAN77FREE, 3-17 
FORTRAN77FREESTR, 3-21 
FORTRAN77LOCK, 3-29 
FORTRAN77LOCKSTR, 3-34 
FORTRAN770PEN, 3-6 
FORTRAN77RECREATE, 3-62 
FORTRAN77SAVETRPOINT, 3-50 
FORTRAN77SECUJIE, 3-37 
FORTRAN77SECURESTR, 3-42 
FORTRAN77SET; 3-13 
FORTRAN77STORE, 3-66 
FORTRAN77VERB, 3-74 
purpose of, 1-4 
table of, 3-1 

< status statement > , executing through 

entry point, 3-76 
store operations, 3-66 
storing records, 3-66 
string variables, use of preinitialized, 1-8 
<string> 

declaring DMINTERPRETER library in 

FORTRAN77, 2-13 
declaring FORTRAN77 entry points, 2-17 
STRUCTURE data set, as entry for 

DATASET-SUBTYPE, 7-4 

< structure > 
finding records, 3-26 
freeing records, 3-18 
locking records, 3-30 

moving character strings to variables, 4-7 
moving double-precision values to 

variables, 4r-22 
moving Kanji character stnngs to 

variables, 4-12 
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moving numeric values to variables, 4-17 
placing double-precision values into data 

items, 4-47 
placing numeric values into data items, 

4^2 

placing strings into data items, 4-32 

placing strings into Kanji alpha items, 4-37 

retrieving Boolean or field items, 4-27 

securing records, 3-38 

setting Boolean values, 4-52 

setting current path, 3-14 

setting null values, 4-56 

storing records, 3-66 
structures 

locking, 3-34 

securing, 3-42 
subcategories for exceptions and errors, 

tables of, B-2 
SUBSET value, as entry for SET-SUBTYPE, 
7-5 

simmiary table of exceptions and errors, 
B-18 

symbolic name, in FORTRAN77, 2-13 
< symbolic name > , declaring 

DMINTERPRETER library, 2-13 
SYNC value, setting when ending transaction 

state, 3-69 

syncpoints, setting when ending transaction 

state, 3-69 
SYSTEM/BUILDINQ, generating 

DMINTERPRETER library, A-1 
SYSTEM/INTERFACE, generating 

DMINTERPRETER library, A-1 
SYSTEMERROR category- 
exception and error subcategories, B-16 
major category number, B-2 



T 

table of exceptions and errors, B-18 
< target > , setting current path, 3-14 
TITLE attribute 

declaring DMINTERPRETER library in 
ALGOL, 2-2 
FORTRAN77, 2-13 
invoking DMINTERPRETER library in 
COBOL, 2-10 
transaction state 
aborting, 3-48 
beginning, 3-45 
canceling, 3-53 



deleting records, 3-56 
ending, 3-69 

saving a transaction point, 3-50 
storing records, 3-66 

< transaction statement >, executing 

throu^ entry point, 3-75 
transferring data 

constructing transfers during program 

execution, 4r-60 
moving character strings to variables, 4-6 
moving double-precision values to 

variables, 4r-21 
moving Kanji alpha character strings to 

variables, 4-11 
moving nimieric values to variables, 4-16 
placing double-precision values into data 

items, 4-46 
pladng numeric values into data items, 

4-41 

placing strings into data items, 4--31 
placing strings into Kanji alpha items, 4-36 
retrieving Boolean values, 4-26 
setting data items to Boolean values, 4-51 
setting data items to nuU values, 4-56 

TYPE entry, for ITEM-SUBTYPE, 7-6 

types of 

application program interfaces, 1-1 
data sets in DBSTRUCTURE data set, 7-4 
entities in DBSTRUCTURE, 7-3 
sets in DBSTRUCTURE data set, 7-5 

u 

< underscore name > 

moving character strings to variables, 4^7 
moving double-precision values to 

variables, 4-22 
moving Kanji character strings to 

variables, 4-12 
moving numeric values to variables, 4-18 
pladng double-precision values into data 

items, 4-47 
placdng nimieric values into data items, 

4-42 

placing strings into data items, 4-32 
placing strings into Kanji alpha items, 4-37 
retrieving Boolean or field items, 4r-27 
setting Boolean values, 4-^2 
setting null values, 4-57 
unlocMng 
recorck, 3-17 
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structures, 3-21 
UNORDERED data set, as entry for 
DATASET-SUBTYPE, 7-t 
update access, 3-6 

UPDATE value, in opening databases, 3-7 

use of DASDL options 
ZIP,A-5 

user work area 

deleting records, 3-56 
folding records, 3-24 

using BUILDINQ program, A-4 

USING clatise, supplying parameters for 
COBOL entry points, 2-11 

using the release tape 

declaring ALGOL entry points, 2-4 
declaring COBOL entry points, 2-8 
declaring FORTRAN?? entry points, 2-14 

V 

< variable name > 

moving character strings to variables, 4r-8 

moving double-precision values to 
variables, 4-23 

moving Kanji strings to variables, 4^-13 

moving nimieric values to variables, 4-18 

retrieving Boolean values, 4-28 
variable-format record 

creating new records, 3-10 

recreating records, 3-63 
verification message, in BUILDINQ program, 
A-12 

VERSIONERROR category 

exception and error subcategories, B-18 
major category number, B-2 

w 

Work Flow Language 

generating the DMINTERPRETER library, 
A-15 

z 

ZIP option, generating the 

DMINTERPRETBR library, A-5 



$INCLUDE compiler control option 
reasons to use, 1-5 
use in ALGOL programs, 2-4 
use in FORTRAN?? programs, 2-14 
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